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 epydoc .
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 namedtuple ), 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 itself: 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:
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 , epydoc and sphinx .
pydoc does not provide facilities for documenting data representation and its HTML output is impossible for me to use productively.
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
sphinx , 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 maintaining it.
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.