Had to recently document a Python library / API; it was not for public consumption. I took inspiration from pyserial [1] and made sparse docstrings which in turn reduced potential clutter making things easier to read and digest; and provide a more elaborate (hand generated) documentation in the sphinx documentation rendered as html/pdf. I quite liked this balance. The obvious trade off is the sphinx documentation may go out of sync with what is in the code, but eh if it happens it won't be the end of the world and is quickly rectified.
pdoc is my go-to documentation tool for small Python projects.
However, when they start to grow, MkDocs and the Material for MkDocs theme make the most sense — they’re easy to install and deploy, and they offer a ton of features for writing engaging documentation.
They write on documenting variable assignments which don't support pythons __doc__ string:
> To compensate, pdoc will read the abstract syntax tree (an abstract representation of the source code) and include all assignment statements immediately followed by a docstring
I can't really understand that. I am programming Python for 14 years now, and any real codebase I have ever seen documents variables above their declaration. Even if there is some technical reason for it, if I saw a python developer comment what a variable declaration means below that declaration I would at least question their taste.
To me that particular implementation is so bad, that I would prefer pdoc without it.
10 comments
[ 4.5 ms ] story [ 32.7 ms ] threadShow HN: Pdoc, a lightweight Python API documentation generator - https://news.ycombinator.com/item?id=25903595 - Jan 2021 (18 comments)
It makes really nice use of python docstrings and is overall just really easy to use!
[1]: https://pythonhosted.org/pyserial/
Are there any libraries similar to Doxylink [2] that ensure that links from Sphinx to pdoc (and vice versa) are valid?
[1] https://news.ycombinator.com/item?id=25903595
[2] https://sphinxcontrib-doxylink.readthedocs.io/en/stable/
However, when they start to grow, MkDocs and the Material for MkDocs theme make the most sense — they’re easy to install and deploy, and they offer a ton of features for writing engaging documentation.
[0] https://www.mkdocs.org/ [1] https://squidfunk.github.io/mkdocs-material/
But there is one blemish.
They write on documenting variable assignments which don't support pythons __doc__ string:
> To compensate, pdoc will read the abstract syntax tree (an abstract representation of the source code) and include all assignment statements immediately followed by a docstring
I can't really understand that. I am programming Python for 14 years now, and any real codebase I have ever seen documents variables above their declaration. Even if there is some technical reason for it, if I saw a python developer comment what a variable declaration means below that declaration I would at least question their taste.
To me that particular implementation is so bad, that I would prefer pdoc without it.