pdoc is a library and a command line program to discover the public
interface of a Python module or package. The
pdoc script can be used to
generate plain text or HTML of a module's public interface, or it can be used
to run an HTTP server that serves generated HTML for installed modules.
It is intended that
pdoc will be a replacement for the unmaintained
To see what generated documentation looks like, check out the documentation for pdoc.
Prominent features include:
- Support for documenting data representation by traversing the abstract syntax to find docstrings for module, class and instance variables.
- For cases where docstrings aren't appropriate (like a
the special variable
__pdoc__can be used in your module to document any identifier in your public interface.
- Usage is simple. Just write your documentation as Markdown. There are no added special syntax rules.
__all__variable when present.
pdocwill automatically link identifiers in your docstrings to its corresponding documentation.
pdocis run as an HTTP server, external linking is supported between packages.
pdocHTTP server will cache generated documentation and automatically regenerate it if the source code has been updated.
- When available, source code for modules, functions and classes can be viewed in the HTML documentation.
- Inheritance is used when possible to infer docstrings for class members.
The above features are explained in more detail in pdoc's documentation.
pdoc has been tested on Python 2.6, 2.7 and 3.3.
pdoc is on PyPI and is installable via
pip install pdoc
Pygments is an optional dependency. When it's installed, source code will have syntax highlighting.
Documentation for the
pdoc library is available from
pdoc.burntsushi.net/pdoc. The documentation
includes a more in depth description of the features listed above.
pdoc will accept a Python module file, package directory or an import path.
For example, to view the documentation for the
csv module in the console:
Or, you could view it by pointing at the file directly:
Submodules are fine too:
You can also filter the documentation with a keyword:
pdoc csv reader
Generate HTML with the
pdoc --html csv
A file called
csv.m.html will be written to the current directory.
Or start an HTTP server that shows documentation for any installed module:
Then open your web browser to
There are many other options to explore. You can see them all by running:
pdoc works well with
virtualenv. If you are documenting a project that is
installed within a
virtualenv environment, you should be able to install
directly into that environment and use it with no further configuration.
pdoc uses idiomatic Python when loading your modules. Therefore, for
to find any submodules of the input module you specify on the command line,
those modules must be available through Python's ordinary module loading process.
This is not a problem for globally installed modules like
sys, but can be
a problem for your own sub-modules depending on how you have installed them.
To ensure that
pdoc can load any submodules imported by the modules you
are generating documentation for, you should add the appropriate directories
PYTHONPATH environment variable.
For example, if a local module
b.py that is installed as
/home/jsmith/pylib/b.py, then you should make sure that your
pdoc cannot load any modules imported by the input module, it will exit
with an error message indicating which module could not be loaded.
It's in the public domain.
At the time of writing, there are three tools I know of that provide automatic
documentation for my Python packages. Those tools are
pydoc does not provide facilities for
documenting data representation and its HTML output is impossible for me to use
sphinx is a tool I have been unable to get working despite
trying and failing several times over the past couple years. Moreover,
automatic API documentation does not seem to be a primary goal of
where prose separate from the source code seems encouraged. If the
documentation for my module is not with my source code, then I have no hope of
epydoc is what I had been using for several years. The last release
was in 2008 and it is not compatible with Python 3. In addition to the web
pages it produces being difficult for me to browse,
epydoc is over 10,000
lines of code (not including comments or HTML generation). By the same measure,
pdoc is under 800 lines of code.