pdoc is back!

[mhils]

Hi folks,

pdoc has picked up steam again and we've just shipped a new stable release. 🚀

This release fixes many longstanding issues, but also removes a few beloved features, namely Markdown output and the __pdoc__ variable. We'll see how far this goes and if we need to add them back. I have also taken the liberty to clean up the issue tracker. If you have any feedback, please don't hesistate to open a new issue!

[fabiosangregorio]

Thank you for picking up the project! This is really awesome, congratulations.

I have always despised using pdoc3 because of his history and the toxicity of the author, but it was the only package that just worked out of the box and was actually pretty good.
I can't wait to feel happier and move to the original pdoc once it gets larger support (e.g. for numpydocs).

PS: I got to know that this package was active again because of Github featured projects! :)

[mhils]

Thanks for the kind words @fabiosangregorio! 😊

The pdoc3 situation is a very unfortunate one. For those unaware, I have added a few words on our perspective in the README: https://github.com/mitmproxy/pdoc#pdoc-vs-pdoc3.

Whatsoever, this is not going to discourage us here. :) Support for some alternative docstring flavors is definitely on my radar. It's unlikely that we add full support for the very complicated ones (reStructuredText), but we're definitely going to improve here more generally. If anyone wants to get this started for their favorite flavor, please do get in touch with me on Slack and I'm happy to help! It's a really fun code base to hack on, and I'm available if there are any questions.

Update: pdoc now supports Google-style and numpydoc docstrings :)

[songololo]

Excited to see this project and glad that it is getting some momentum again.

A vote for adding-back markdown output if possible as this can be really useful for outputting content to other static build systems.

[mhils]

@songololo: PRs welcome! 😃

For most static build systems, I recommend taking the HTML output, which just renders more nicely overall. Most Markdown-based site generators happily take HTML. We have an example for mkdocs at examples/mkdocs!

[alexisrolland]

Thank you for supporting this project!

I also vote for adding pure markdown outputs. The benefit of markdown is to be able to apply a consistent styling according to the platform where it is published. HTML on the other side will embed undesired styling. It would be lovely to have pure .md files.

[mhils]

Hi there! 😃 pdoc currently only supports HTML output, although Markdown would be relatively easy to add. That being said, if your end format is HTML anyway, pdoc's HTML + CSS is deliberately written in a way that makes it very easy to embed into other contexts. If you haven't seen it, https://pdoc.dev/docs/pdoc.html#integrate-pdoc-into-other-systems provides some more details.

[BurntSushi]

FWIW, pdoc originally had Markdown output so that one could read docs on the command line in your terminal. That was its primary use case for me anyway.

[mhils]

Right - I think that viewing docs on the command line is covered reasonably well by pydoc nowadays, which comes as part of Python. I'm not opposed to re-adding similar functionality to pdoc again, PRs are definitely welcome. :)

I've just pushed https://github.com/mitmproxy/pdoc/tree/markdown, which wires up an -f markdown command line option. If someone is interested in writing the output template, I'd be happy to do the leg work and get tests running etc. 😃

[hhalaby]

@mhils

The pdoc3 situation is a very unfortunate one. For those unaware, I have added a few words on our perspective in the README: https://github.com/mitmproxy/pdoc#pdoc-vs-pdoc3.

I'm currently trying to decide if I should use pdoc or pdoc3 and I don't understand why people still assume that the author of pdoc3 has malicious intents. He expressly stated that his use of that symbol is of Buddhist origin...

[BurntSushi]

@HoussamHalaby That wasn't the only problem I cited.

[trallnag]

In my case I had to switch to "this" pdoc from pdoc3 because I ran into some weird issues around Python Poetry + global Pre-commit and having pdoc3 installed inside the venv. For some reason when I ran it with local hooks it also generated docs for all my tests and broke because of hacky import magic in the tests.

Beyond that I don't care

[davfsa]

Hey, I just wanted to ask a question related to this announcement. With the removal of the __pdoc__ variable, what would it be the ideal way to stop a specific variable/method/class from being documented?

PS: Just wanted to thank you for picking the project back up!