Open epogrebnyak opened 2 years ago
Here are some thoughts on usecase and possible enhancements, after settign up a trial project and looking at code.
Great:
Minor patches for docs:
develop
index.rst is already created - maybe change text in docsMore usecases (need priritisation):
mudkip apidoc <MODULE>
?overrides
section work this way?)build -b <builder>
optionSlight alternatives or possible changes in behavior:
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)mudkip gh-pages
mudkip develop
is a zero-config starterImplementation detail:
Needs clarification:
Config
?@vberlier - your comment on what of these changes is welcome in the project highly appreciated
Implementation detail (addition):
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.
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.
@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?
Oh, the latex builder already there, could not see around dependabot commits. Will try out and close #206. Thanks for such quick updates!
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).