5 ms·

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 assumi

by mhils 6y ago

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 https://github.com/mitmproxy/pdoc#pdoc-vs-pdoc3

woile 6y ago
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!
- mhils 6y ago
  > 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?
  - kylebarron 6y ago
    > 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/ https://www.mkdocs.org/user-guide/plugins/
    - woile 6y ago
      Mkdocs has a plugin to generate apidocs as well https://github.com/tomchristie/mkautodoc https://github.com/tomchristie/mkautodoc
kingosticks 6y ago
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 https://github.com/timothycrosley/pdocs [1] https://github.com/timothycrosley/pdocs/#differences-between-pdocs-and-pdoc https://github.com/timothycrosley/pdocs/#differences-between...
- mhils 6y ago
  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. :)
  - kylebarron 6y ago
    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/ https://cogeotiff.github.io/rio-tiler/api/rio_tiler/io/cogeo... Though I have to say your HTML output looks quite nice.
    - mhils 6y ago
      Definitely, I'd be happy to merge a PR! But nothing wrong with using pdocs. :)
timvdalen 6y ago
That has to be one of the strangest interactions on GitHub issues I've ever read.

by mhils 6y ago

woile 6y ago

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!

mhils 6y ago
> 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?
- kylebarron 6y ago
  > 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/ https://www.mkdocs.org/user-guide/plugins/
  - woile 6y ago
    Mkdocs has a plugin to generate apidocs as well https://github.com/tomchristie/mkautodoc https://github.com/tomchristie/mkautodoc

kingosticks 6y ago

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 https://github.com/timothycrosley/pdocs [1] https://github.com/timothycrosley/pdocs/#differences-between-pdocs-and-pdoc https://github.com/timothycrosley/pdocs/#differences-between...

mhils 6y ago
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. :)
- kylebarron 6y ago
  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/ https://cogeotiff.github.io/rio-tiler/api/rio_tiler/io/cogeo... Though I have to say your HTML output looks quite nice.
  - mhils 6y ago
    Definitely, I'd be happy to merge a PR! But nothing wrong with using pdocs. :)

timvdalen 6y ago

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