Factsheet
Project Origins
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." (Some further information and discussion is available on issue #203 pdoc is back!.
From this Python Wiki edit, it appears that pdoc was (and still is) the original project, and the pdoc3 maintainer forked it. (It's not clear who made that change, but it deleted all reference to the original project, which strikes me as a possible warning sign about the pdoc3 community. For more on this, see below.)
Technical Differences
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.
Community Controversies
The pdoc README has a section pdoc vs. pdoc3 claiming that pdoc3 "falsely assumes [the pdoc] name," mentioning the deletion of the original pdoc from the Python wiki, and giving other indications of some antagonism in the pdoc3 community. There's further discussion in various PRs, including pdoc#203, pdoc3#346, and [pdoc3#377]; particularly demonstrative are comments such as [1], [2] and [3].
The key difference between pdoc and pdoc3 is in their development and functionality. pdoc was the original tool for generating Python documentation, but its development has stopped, making it outdated for modern projects. In contrast, pdoc3 is an actively maintained fork of pdoc that brings several improvements, like better support for Python 3 features (including type hints and async functions), improved Markdown rendering, customizable templates, and a live-preview server for documentation. While pdoc is no longer widely used, pdoc3 has become a more reliable and feature-packed option for creating Python project documentation.
python -m pydoc -w module_folder/ will work for some scenarios, but not all. For example, if you want to document modules and submodules of an installed package, it won't work, you'd need to pivot to a different tool.
Using your favorite language you will need to:
- Iterate through files in your target folder
- Call pydoc once per (sub)module
Here is one of many examples on Github.
Pdoc, pydoctor both handle walking folders automatically, my fork of pydoc walks the module dependency tree by default.
I have found a way to do it.
1/
Create in the root directory of your source code a module doc_generator.py
2/
Paste this code in the freshly created module:
import pydoc
path = "."
pydoc.writedocs(path)
3/
Execute the module.
It should create a html per module and well include all your packages.
Gather all html files created...it's your documentation.
You can set PYTHONPATH env variable. This is a path that say python where to find modules and packages by 3th party also you.
When using pdoc with my Spyder IDE, I use the following script to add a directory to pdoc path
import pdoc
libpath = r'C:\Path\To\Module'
pdoc.import_path.append(libpath)
mod = pdoc.import_module('ModuleName')
doc = pdoc.Module(mod)
string = doc.html()
The pdoc.import_path is a list of currently used paths to look for your module; pdoc.import_path equals sys.path in default. More info can be found in pdoc documentation.
If you really want to use Pydoc, you can simply do in a terminal:
$ pydoc -w myproject
This will generate an old-school HTML documentation from doctrings.
Note that Pydoc is the module used in Python since 2.1 for the help() function.
It will retrieve the docstrings which are NOT comments. You should describe your functions using docstrings.
But it is a kind of old-school using Pydoc for documentation generating. The popular tool to do that in Python is Sphinx. But you'll need to format your docstrings in a particular format as reStructuredText.
You could also use pdoc, which auto-extracts documentation from your docstrings (i.e. public API) and supports markdown, numpydoc, google-style docstrings format and some reStructuredText directives.
Have a look here to get some information concerning docstrings formatting.
You can also use Pyment to generate docstring skeletons or convert existing ones to a particular format.
Alternatively, if you want a simple text file instead of HTML, you can redirect the console output to a file with this simple command:
$ pydoc myproject > helpfile.txt
This file can be printed or uploaded to Github without too much additional effort.