Python Continuous Documentation
github.com
github.com
All being said, Sphinx is a decent tool (and I wrote WAAY too much of it in the last three years), but I have grown to strongly dislike reStructured Text -- I have to look up the URL linking syntax, for instance, almost every time I use it.
Having something like Sphinx that ate Markdown instead would make me rather happy.
I'm not sure fragmenting doc string syntax further is a good idea for the python community. There's been efforts to support Markdown on pypi for README.md. But even that has been met with a lot of resistance.
I can't wait for the python PEP standards for function-annotation to become standard and permeate the editors.
That said, I use sphinx a lot. I think it's a totally fine tool
There is no access to Sphinx's directives/extensions, as it implements Commonmark support, which doesn't yet offer an extension syntax as part of the spec. Once it does, writing in Markdown will me more useful, but currently it's limited to basic markup and naive linking.
(It doesn’t make sense to spend resources on having units documented separately from code, because you don’t need such docs unless you’re working with code. Loads of auto-generated docs also gives a false impression of your project being properly documented, which it isn’t unless you also have higher-level hand-written documentation somewhere.
Similarly, it doesn’t make sense to keep high-level architecture docs in docstrings, as it’s not tied to specific modules, and you normally need it when you’re thinking big picture as opposed to working with specific code units.)
Overall, kudos—good documentation is important.
If you’re concerned about writing good documentation, I recommend reading these series by Jacob Kaplan-Moss (of Django core development team): https://jacobian.org/writing/great-documentation/