Show HN: Pdoc, a lightweight Python API documentation generator | Hacker News Reader

Show HN: Pdoc, a lightweight Python API documentation generator

pdoc.dev

45 pointsmhils18 comments

Hi HN! Some of you may remember @BurntSushi's pdoc tool, a lightweight alternative to Sphinx. We're a bit in an unfortunate situation with a hostile work assuming our name [1], but I figured that we shouldn't give in and continue the legacy of that tool. Long story short, we have just published a major new "modern Python 3" release, which hopefully makes pdoc a really compelling option again. :-)

[1] https://github.com/mitmproxy/pdoc#pdoc-vs-pdoc3

This is really awesome thanks for sharing. And it even supports markdown by default, fantastic!

Some questions:

- is it possible to include a folder with md files in the output? similar to what mkdoc does. - any plans to suppport `##` or `# #` (for pep8) similar to rust's `///`?

Thanks!

> is it possible to include a folder with md files in the output?

Not yet, but integrating your API documentation into the rest of your website/docs is definitely something that I have on the radar. I'm not sure what this will look like eventually. :-) If you have specific ideas, please do open an issue on GitHub for some brainstorming!

> any plans to suppport `##` or `# #` (for pep8) similar to rust's `///`?

Unlikely. To generate documentation, we introspect the loaded module and also walk the abstract syntax tree. Python's builtin AST does not include comments, so there's no easy way for us to access them. Honestly, I think the """docstrings""" convention is reasonable enough and widely adopted in the Python ecosystem. Is that missing any use cases?

> integrating your API documentation into the rest of your website/docs is definitely something that I have on the radar

I think that Sphinx and mkdocs are the two most popular docs systems for Python, and Sphinx can build its own API docs, so a closer integration into mkdocs might be worth looking into. Mkdocs has a plugin system now that you can hook in to

[0]: https://www.mkdocs.org/user-guide/plugins/

Mkdocs has a plugin to generate apidocs as well

https://github.com/tomchristie/mkautodoc

I hadn't heard of this and it looks great. But then I also came across pdocs[0]. Other than the 3rd bullet which looks outdated, how does the rest of the comparison[1] hold up? And do you really not support Python3.7? Isn't Debian Stable using Python3.7?

[0] https://github.com/timothycrosley/pdocs

[1] https://github.com/timothycrosley/pdocs/#differences-between...

pdocs is what a friendly fork looks like, happy to see it. :) I've sent an email to Timothy a few days ago, I'd be more than happy to eventually join forces. We also invited the pdoc3 author early on to collaborate under the only condition that he'd need to change his swastika avatar to something less offensive, but alas. :/

Regarding the comparion to pdocs:

  - We only support HTML output at the moment, pdocs does support Markdown.
  - Type annotations are now a first class citizen in pdoc, including string forward references.
  - 3.8 is a requirement for pdoc, but you can use it to document 3.5 code.
  - pdoc now uses tox, mypy, flake8, GitHub Actions... and has 100% test coverage :)
  - and we also have a Python API: https://pdoc.dev/docs/pdoc.html#pdoc

Overall, I think we try to be a bit simpler compared to pdocs. For example, we use argparse instead of hug to not introduce additional dependencies, and we really focus on the "generate standalone documentation" use case. That being said, I can recommend pdocs just as well. :)

Are you interested in adding support for Markdown output? We're using pdocs specifically so that we can integrate it inside mkdocs output.

Example API docs from pdocs, rendered in mkdocs: https://cogeotiff.github.io/rio-tiler/api/rio_tiler/io/cogeo...

Though I have to say your HTML output looks quite nice.

Definitely, I'd be happy to merge a PR! But nothing wrong with using pdocs. :)

That has to be one of the strangest interactions on GitHub issues I've ever read.

I recently tried to use pdoc on a system that can never have internet connectivity. Looks like pdoc implicitly expects internet connectivity because it wants to get at a bunch of .js and css files online.

Did I just overlook something?

If the tool really does expect connectivity, any plans to inline these resources so pdoc can be fully capable of running on an offline system?

It's so much easier to setup and get going with than Sphinx that it seems a real shame to have to be online.

pdoc produces completely standalone HTML files with no dependencies and no JS. Even the collapsible navigation on small screen sizes is implemented in CSS only. Take a look yourself: https://pdoc.dev/docs/pdoc.html

You were probably using pdoc3, a hostile fork. See my other post. :(

Ah, yes, so I was. Sorry to sow the very confusion you're trying to obliterate.

This looks great! Do you have plans on producing JSON output in addition to HTML output? I have a larger custom website in which I need to embed my Python documentation in. I currently rely on Sphinx for this, but would love to switch over to something simpler.

What kind of JSON format would you be looking for? Is there some sort of standard I'm not aware of? Generally speaking it's quite easy to change the output format, one just needs to swap out the Jinja2 template. :)

The python >3.8 requirement broke the use case for me. I know that there is support for creating API's on python 3.5+. It's just not worth it to upgrade to 3.8 to create docs and then downgrade again to 3.7 run the actual code.

A bit of a late reply, but Python 3.7 is supported now! :)

Looks simpler than Sphinx. I may give it a try

Reply on news.ycombinator.com