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!

[mhils]

@davfsa: We have that covered in the documentation: https://pdoc.dev/docs/pdoc.html#control-what-is-documented :)

[davfsa]

@davfsa: We have that covered in the documentation: https://pdoc.dev/docs/pdoc.html#control-what-is-documented :)

Thanks for the quick reply. In our case I would like to hide a public function that is meant for internal use only (it is an alternative to the init that we would like to keep private as it removes all the safety checks from there). For that we used __pdoc__ to hide it from being documented. Since that is not possible anymore I will look into implementing the hiding myself. Keep up the amazing work!

[mhils]

That sounds like you actually want to signal that it is private by prefixing it with _. 😉 As a last resort, you can also override is_public to hide stuff, it works both ways. :)

[zeelot]

hey any chance we can create a ticket for the markdown output support? I saw there is one that was closed but the markdown branch is over a hundred commits behind and I would love to track it properly :)

there's quite a bit wrong with simply renaming html files to md files right now. I am using mkdocs but, for example, the search feature of mkdocs will pick up on the html and show a lot of nonsense in the results because of it. I'm also struggling with links not working because of differences in how mkdocs treats files as directories in the URL but pdoc links to html files (that do not exist). I think proper markdown output support would make this challenge at least a tiny bit easier since the jinja templates should be simpler to modify to fit any weird mkdocs→pdoc linking issues.

thanks for the work!

[mhils]

@zeelot: See #308! 😃

[ekwan]

Wooooooo! Thanks for working on this project!

[kwshi]

I don't mean to derail this thread, but I'd like to offer my read on the pdoc3 drama, which I hope is helpful to anyone else confused about the situation (as I also was initially). I'm not going to reply to anything after this, in a (perhaps futile) attempt to avoid hijacking this thread into a flame war. (Preemptive sorry to the maintainers if you end up having to lock this thread!)

@hhalaby

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...

The issue is that intention isn't end-all-be-all. Even though the pdoc3 author allegedly intends his use of the swastika to be in the Buddhist sense, nobody can deny that the predominant cultural perception of this symbol is associated with the Nazi sense. Unless there are very explicit, unambiguous disclaimers accompanying every occurrence of the symbol (e.g., "note: this use of the swastika is of Buddhist origin, expressly not associated with Nazi ideology"), which there weren't on the pdoc3 website at the time this discussion occurred, it's silly to expect others not to default to the more common interpretation. It's a little bit like loudly announcing "I'm gay", with no elaboration, and then getting pissed off at everyone who congratulates you on coming out of the closet. The way the author responded in that thread reads to me as immature at best, and at worst deliberately obtuse and/or dishonest about his true underlying intentions.

Even setting that aside (the swastika symbol has since been removed from the pdoc3 website), and even besides the issue of pdoc3 trying to take over the pdoc name, still the pdoc3 author comes off as rude and regressive in other aspects. For example, there is an insensitive and tasteless quote about sex on the front page of pdoc3, and when community members raised this concern (pdoc3/pdoc#346) the author was entirely dismissive, choosing to respond with sarcasm, branding them as "empathetic warriors", while completely ignoring the actual substance of their concerns. Make of that what you will, but to me, this rings of reactionary "anti-woke"-ism, and that kind of value system is just a dealbreaker for me.

[hhalaby]

@kwshi Two years later, I feel that my previous reaction was naive. I always try to give people the benefit of the doubt but now I see that the author of pdoc3 does indeed come off as immature at best :) thanks for the explanation.