5 ms·

Pdoc – Generate API documentation for Python projects

114 points by joshdavham 1y ago

dang 1y ago
Related. Others? Show HN: Pdoc, a lightweight Python API documentation generator - https://news.ycombinator.com/item?id=25903595 https://news.ycombinator.com/item?id=25903595 - Jan 2021 (18 comments)
joshdavham 1y ago
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!
commandersaki 1y ago
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/ https://pythonhosted.org/pyserial/
- gcr 1y ago
  Hey I’m in the process of documenting a library for my startup, do you have any more thoughts about your process?
  - commandersaki 1y ago
    I would just say follow pyserial example if that is something you like; look at their source code docstrings vs the documentation including the API bits. 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.
kaycebasques 1y ago
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 https://news.ycombinator.com/item?id=25903595 [2] https://sphinxcontrib-doxylink.readthedocs.io/en/stable/ https://sphinxcontrib-doxylink.readthedocs.io/en/stable/
- mhils 1y ago
  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/ https://lychee.cli.rs/. :)
globalhsbc 1y ago
[dead]
darkamaul 1y ago
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/ https://www.mkdocs.org/ [1] https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/
- klabetron 1y ago
  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
  - darkamaul 1y ago
    You can't directly but there is a plugin for this: https://mkdocstrings.github.io/ https://mkdocstrings.github.io/ Example here: https://quarkslab.github.io/quokka/reference/python/executable/ https://quarkslab.github.io/quokka/reference/python/executab...
scosman 1y ago
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.
atoav 1y ago
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.
- hk__2 1y ago
  > 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.
  - WhyNotHugo 1y ago
    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.
    - burntsushi 1y ago
      Sphinx is the one who invented new syntax. I just used the syntax Python already had for docstrings, but extended it to variables. Also, when I first wrote pdoc, it was at a time of immense frustration with both Sphinx and reST.
    - stuaxo 1y ago
mhils 1y ago
pdoc maintainer here. Pleasant surprise to see us on HN again, and happy to answer any questions! :)
- packetlost 1y ago
  Any chance we could get a better solution to this problem: https://git.sr.ht/~chiefnoah/pybare/tree/master/item/pdoc_index_workaround.py https://git.sr.ht/~chiefnoah/pybare/tree/master/item/pdoc_in... 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.
  - mhils 1y ago
    pdoc3 is not pdoc, see https://github.com/mitmproxy/pdoc?tab=readme-ov-file#pdoc-vs-pdoc3 https://github.com/mitmproxy/pdoc?tab=readme-ov-file#pdoc-vs....
    - packetlost 1y ago
      ah, dang I forgot about that split.

114 points by joshdavham 1y ago

dang 1y ago

Related. Others? Show HN: Pdoc, a lightweight Python API documentation generator - https://news.ycombinator.com/item?id=25903595 https://news.ycombinator.com/item?id=25903595 - Jan 2021 (18 comments)

joshdavham 1y ago

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!

commandersaki 1y ago

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/ https://pythonhosted.org/pyserial/

gcr 1y ago
Hey I’m in the process of documenting a library for my startup, do you have any more thoughts about your process?
- commandersaki 1y ago
  I would just say follow pyserial example if that is something you like; look at their source code docstrings vs the documentation including the API bits. 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.

kaycebasques 1y ago

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 https://news.ycombinator.com/item?id=25903595 [2] https://sphinxcontrib-doxylink.readthedocs.io/en/stable/ https://sphinxcontrib-doxylink.readthedocs.io/en/stable/

mhils 1y ago
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/ https://lychee.cli.rs/. :)

globalhsbc 1y ago

[dead]

darkamaul 1y ago

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/ https://www.mkdocs.org/ [1] https://squidfunk.github.io/mkdocs-material/ https://squidfunk.github.io/mkdocs-material/

klabetron 1y ago
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
- darkamaul 1y ago
  You can't directly but there is a plugin for this: https://mkdocstrings.github.io/ https://mkdocstrings.github.io/ Example here: https://quarkslab.github.io/quokka/reference/python/executable/ https://quarkslab.github.io/quokka/reference/python/executab...

scosman 1y ago

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.

atoav 1y ago

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.

hk__2 1y ago
> 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.
- WhyNotHugo 1y ago
  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.
  - burntsushi 1y ago
    Sphinx is the one who invented new syntax. I just used the syntax Python already had for docstrings, but extended it to variables. Also, when I first wrote pdoc, it was at a time of immense frustration with both Sphinx and reST.
  - stuaxo 1y ago

mhils 1y ago

pdoc maintainer here. Pleasant surprise to see us on HN again, and happy to answer any questions! :)

packetlost 1y ago
Any chance we could get a better solution to this problem: https://git.sr.ht/~chiefnoah/pybare/tree/master/item/pdoc_index_workaround.py https://git.sr.ht/~chiefnoah/pybare/tree/master/item/pdoc_in... 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.
- mhils 1y ago
  pdoc3 is not pdoc, see https://github.com/mitmproxy/pdoc?tab=readme-ov-file#pdoc-vs-pdoc3 https://github.com/mitmproxy/pdoc?tab=readme-ov-file#pdoc-vs....
  - packetlost 1y ago
    ah, dang I forgot about that split.