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.
[0] https://www.mkdocs.org/ [1] https://squidfunk.github.io/mkdocs-material/
Love MkDocs* even for non-Python. But, wasn’t aware it could auto-generate from code comments like pdoc? I’d assume one would use pdoc for the API section of a hot mkdocs layout.
*not just because my initials are MK
You can't directly but there is a plugin for this: https://mkdocstrings.github.io/
Example here: https://quarkslab.github.io/quokka/reference/python/executab...
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/
I'd say neither fork as made great strides since then, but I'm also biased here as the maintainer of pdoc.
There is no pdoc-specific library for link checking as far as I'm aware. It's all plain HTML though, so you can use a more general tool like https://lychee.cli.rs/. :)
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.
Related. Others?
Show HN: Pdoc, a lightweight Python API documentation generator - https://news.ycombinator.com/item?id=25903595 - Jan 2021 (18 comments)
Pdoc is great. I tried mkdoc and others, but pdoc was so much easier. One command and you're done. Trivial to add to a Github workflow & Github pages.
Pdoc is great. I love it.
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.
> 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.
It’s standard to write docstrings below the declaration they refer to. What you are refering to are comments, not docstrings. I’ve been programming in Python for 15 years and I learnt this quite recently. This gives you in-editor documentation for class attributes and other non-functions.
Sphinx reads comments starting with #: above class variables and uses them for documentation.
I wonder why they didn’t take the same approach here and invented a new syntax.
Let me try to explain why it is that way: First, it's consistent with Python functions. The docstring for functions is below the signature as well. Second, consider a file with only a docstring and then a variable declaration. Here it would be ambiguous if that's the module or the variable docstring. Finally, this behavior is consistent with other tools (and failed standardization efforts) in the space. So yeah - I share your sentiment, but I think it's the most pragmatic approach for pdoc. :)
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!
pdoc maintainer here. Pleasant surprise to see us on HN again, and happy to answer any questions! :)