I’ve found what appear to be two forks of the pdoc documentation generator
pdoc (GitHub) and pdoc3 (GitHub). From
comparing the commit graphs, these appear to have split in mid-2018, but
perhaps later, or perhaps there are some commits crossing between the two.
The differences I’ve seen are:
-
pdoc:
- PyPI: 1st release 2013-08-09; v14.4.0 released 2024-01-18
- Github: 48 contributors, used by 2.6k, 189 forks, starred by 1.8k
- Moderate commit activity over the last year
- Hosted under a GitHub personal account
-
pdoc3:
- PyPI: 1st release 2019-01-25; v0.10.0 released 2021-08-03
- Github: 64 contributors, used by 3.8k, 143 forks, starred by 1.1k
- Little commit activity in the last year and a half
- Hosted under a GitHub organisation, but it has only one member
From the releases it looks as if pdoc3 is a fork of pdoc, Per my answer below, pdoc appears to be a fork of pdoc3 (though both seem to have gone for years unmaintained after the split point) but, I can’t see
any explanation of why it forked or what the differences are. Given that,
and the slower pace of commits, it seems to me surprising that it has more
“users” (which I believe are projects with a requirements.txt referencing
it) than pdoc.
At any rate, I don’t necessarily need the details of why the split
happened, but I would like to know what features pdoc3 provides that pdoc
doesn’t, and vice versa, as well as anything else relevant to making a
choice between the two.
NOTE: I am not asking anybody to recommend one over the other, nor am I interested in such recommendations. I am interested only in facts about each that are useful in making that decision myself. (That decision will depend not only on the information provided in answers, but many other factors of the given project or purpose for which it’s being considered.)
3
From the CHANGELOG files, pdoc and pdoc3 appear to have diverged between release 0.3.1 (2014-12-02) and the subsequent release:
- pdoc3 0.5.0 (2019-01-10). This release is relicensed as AGPL-3.0 and is a “Major refactoring, [adding] Python 3 compatibility.”
- pdoc 1.0.0 (2021-01-19), with an undated 0.3.2 bugfix release before that. The 1.0 release notes indicate that it’s a major rewrite, dropping Python 2 support and “is now maintained by @mhils and the mitmproxy team.”
Here are some differences between pdoc and pdoc3 that I’ve discovered. This is just random stuff I’ve picked up along the way while doing research; the list is in no way comprehensive, and some of it may not even be fully correct. (Corrections welcome; just edit this answer.)
-
pdoc appears to have more maintenance effort devoted towards it, given the greater frequency of commits. This is not necessarily meaningful in any way; take it with a huge grain of salt.
-
pdoc3 supports the additional
#:comment syntax for docstrings. -
pdoc supports adding
@private(v14.0.0) and@public(v14.4.0) annotations to method docstrings to suppress/enforce documentation generation (the latter for e.g. methods whose name starts with an underscore). -
pdoc3 supports using
__pdoc__to override docstrings. This was removed from pdoc in the 1.0.0 release (2021-01-19) because it “is rarely required.” -
pdoc3 can generate both PDF and HTML documentation; pdoc generates only HTML.