It makes really nice use of python docstrings and is overall just really easy to use!
If that's something you like, then just lift their documentation/ wholesale and tailor it to your needs, which is how I started. I also tweaked the sphinx settings to generate a pdf as well, but that was a special thing for the customer we were delivering the library and documentation to.
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/
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/. :)
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/
*not just because my initials are MK
Example here: https://quarkslab.github.io/quokka/reference/python/executab...
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.
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.
I wonder why they didn’t take the same approach here and invented a new syntax.
Also, when I first wrote pdoc, it was at a time of immense frustration with both Sphinx and reST.
I much prefer the way Rust did it, so just a separate type of comment-prefix for docstrings. In Rust a regular comment may be
// this is a comment
foo = 1.5;
/// this shows up in docs
foo = 1.5;
my_var = 5
"documentation for my_var"
def my_func():
"documentation for my_func"
and since sphinx is the documentation tool of choice by the python core devs to document python itself, i have to assume they've given this design pattern at least tacit approval... :shrug:
There's a workaround for this case (relevant issue has a link at the top), which is cool, but it uses an "internal" function to solve it, which is not.
dang•4mo ago
Show HN: Pdoc, a lightweight Python API documentation generator - https://news.ycombinator.com/item?id=25903595 - Jan 2021 (18 comments)