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.
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.
[1]: https://pythonhosted.org/pyserial/
In the 2021 thread [1] that dang linked to, there was some discussion of friendly and hostile forks. What's the status of the forks?
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/
Related. Others?
Show HN: Pdoc, a lightweight Python API documentation generator - https://news.ycombinator.com/item?id=25903595 - Jan 2021 (18 comments)
I'm a big fan of pdoc and have used it in a couple projects.
It makes really nice use of python docstrings and is overall just really easy to use!