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.
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.
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/
[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/
Show 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!