I think inline #documentation is an important tool to making software readable. It makes software maintainable, encourages future development and makes it easier to join the project as a developer.
This is why I advocate for #mastodon to start encouraging inline documentation with #yardoc, requiring it for any new PRs and serving this API documentation on joinmastodon.org.
I used to believe in literate programming, but as more time has gone on, we actually see literate programming used less and less, and I think this is actually a good thing.
I'm curious if you know of a similar tool to yardoc for Python?
@serge many of the projects we use in Python, like #Flask, are documented using #Sphinx, which can be configured to automatically generate API documentation from Python source code:
https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html
This is (similar to the #yardoc and #rdoc situation) backwards compatible with #pydoc, though much more expressive due to the machine-readable format for defining parameters, return values and potential exceptions:
https://www.sphinx-doc.org/en/master/tutorial/automatic-doc-generation.html
I personally prefer Material for mkdocs over sphinx. One of the advantages is using markdown instead of restructured text.
Going from inline docs to documentation requires mkdocstrings.
As an example what is possible types.py + bovine.crypto.types.md become this documentation page.
I don't quite understand that difference. #PyDoc uses either docstrings or the comments above a function/module/class/etc. as the comment I'd expect Sphinx to do the same:
https://docs.python.org/3/library/pydoc.html (see paragraph two).
CSDUMMI
Serge from Babka
Helge
