awesome project idea - good runner really needed for sphinx

[epogrebnyak]

I just installed mudkip and opened an empty index.rst - but so impressed by ease of use mudkip. Thank you for developing it!

My initial reaction is to suggest adding https://github.com/executablebooks/sphinx-book-theme to presets, but would need prioritize ideas on how to make mudkip even more usable (below).

[epogrebnyak]

Here are some thoughts on usecase and possible enhancements, after settign up a trial project and looking at code.

Great:

• I believe this project is much needed
• poetry + click + black all very modern stack
• server live reload is magic
• myst paser for enhanced markdown!
• notebook usage!
• human-usable, zero-config sphinx is a great philosophy

Minor patches for docs:

• docs: docs tell If you create index.rst..., but after develop index.rst is already created - maybe change text in docs
• docs: had to google what mudkip is, can also add to docs (a pokemon with superpowers)
• add more themes in project description - make project more visible on github, topics are sphinx-theme, sphinx-doc, etc
• which SSG use Docutils XML as source - seems a great option to make a publishing pipeline, but could not find which SSG can it be

More usecases (need priritisation):

• sphinx-apidoc equivalent as in #185 by @cvauclair - a separate command mudkip apidoc <MODULE>?
• use mudkip.toml as conf.py alternative (does overrides section work this way?)
• document vitepress pipeline, maybe an example of npm-based frontend
• youtube sortcode (as a sidenote Nikola happens to be very rich in replicating Hugo shortcodes - see here)
• build pdf (this is one of main selling points of sphinx for me), maybe build -b <builder> option
• maybe add toctree directive in sample index.rst - this next I personally have to google when setting up documentation
• more themes - eg pydata and executable books - as preset or some other simple way to add them quickly

Slight alternatives or possible changes in behavior:

• alias for build --update-gh-pages:
  • mudkip publish - similar to poetry publish
  • mudkip publish gh-pages (explicitly specify gh-pages as target, as someone may want to publush to netlify, etc)
  • or mudkip gh-pages
• write default options to mudkip.toml explicitly
• make init mandatory if docs not present - however this is a bit at odds with the orginal idea is that mudkip develop is a zero-config starter

Implementation detail:

• build own docs for mudkip using mudkip (link to README.md + automodule)
• gradually use mypy or pyright for type checking
• can use ghp-import to publish to GH Pages
• dataclasses as config options, this style of coding issue - there are quite heavy class constructors with a lot of logic, maybe separate data as dataclasses from their processing
• perhaps we duplicate defaults (eg localhost and port)

Needs clarification:

• not sure why dev server linked to themes? I think dev server should start on any theme.
• why themes register is a class variable? Seems a simple dictionary can do
• how do we avoid conf.py? by suppling all options in Config?
• personal preference - doctests not as important for me compared to mermaid for example - not sure if all built-in sphinx extensions are activated

[epogrebnyak]

@vberlier - your comment on what of these changes is welcome in the project highly appreciated

[epogrebnyak]

Implementation detail (addition):

• maybe remove .vscode and poetry.toml from the repo and add them to .gitignore, they are rather personal config preferences

[vberlier]

Hi! Thanks for checking out the project :)

I started mudkip over 3 years ago, primarily for my own use at first, and evolving it into something more robust over time. I'll admit that with the organic growth, some aspects of the codebase could use a little refactoring. However since the internals don't really matter for end-users it's never really been a priority. Also yeah at the time I was naming personal projects after pokémons haha

sphinx-book-theme / pydata

These would make nice additions to mudkip. Should be pretty easy to add.

sphinx-apidoc

While you should already be able to use sphinx-apidoc with mudkip, I agree it could make sense to have it integrated more tightly into the DX.

mudkip.toml

The overrides section is indeed for configuring anything you would put directly in conf.py.

xml / custom js frontend / vitepress

The docutils xml export isn't something that's understood by any SSG at the moment, it's meant to be used as a data source with a custom frontend. I've been looking at https://vitepress.vuejs.org/ and trying to bridge the gap between its own build system and mudkip using a plugin that can load the xml files. I think the JS community in general has better frontends and it would be nice to get the best of both worlds by leveraging sphinx's authoring experience and ecosystem with the modern UX of a JS SSG. However this isn't really fleshed out yet, and the furo theme is serving me quite well for now so it hasn't been a priority.

youtube

Definitely makes sense to include something like this in mudkip.

pdf

I haven't needed it in a long time but I agree there should be a way to export pdf.

ghp-import

I wasn't aware of this project. If it can work as a drop-in replacement for the current implementation why not.

init / starter

I agree that mudkip init could include more things but it's important to not overwhelm the user either. I also don't want to rely on it too much since it kind of goes against the "zero config" experience but we can work on some improvements there.

static typing

Last time I checked sphinx didn't have types, which means that adding static typing to mudkip would have been really annoying. This probably changed since then. I typically use pyright.

mermaid

Seems reasonable, should be easy to enable.

.vscode / poetry.toml

In my experience these can help beginners get the project working on their machine more easily. The settings aren't that opinionated so I tend to include them in the repo.

[epogrebnyak]

@vberlier - thanks a lot for comments, helps a lot!

Quick replies on two aspects:

• had some bad experience with in-project=true in poetry.toml if black hits the env folder, but agree in-project is more visible and helps delete a folder quickly if things go wrong as it sometimes happens with poetry

• typing idea (pyright) meant for mudkip itself, not sphinx - typing usually helps trace and understand things for outside developpers - can add gradually.

Should I try some pull requests for documentation changes while impressions are still fresh and maybe pdf / -b builder idea for code?

[epogrebnyak]

Oh, the latex builder already there, could not see around dependabot commits. Will try out and close #206. Thanks for such quick updates!