What it is
pdoc is an API documentation generator for Python 3+ projects, published to PyPI as the package pdoc3 and maintained under the AGPL-3.0 license. It lives in the Python ecosystem, and it is itself a Python tool: it accepts a Python module file, a package directory, or an import path, then produces documentation. The project has existed for eight years, carries 1,181 stars and 145 forks, and its own documentation site is generated with pdoc.
The concrete problem it solves is the gap between docstrings that already exist in source code and documentation a reader can actually browse. Rather than requiring a separate authoring format or a configuration-heavy build, pdoc reads the docstrings, type annotations, and variable definitions already present in a project and renders them into HTML documentation. It aims to produce sensible API documentation with prose without any special configuration, which means a project with reasonable docstrings gets a browsable reference without a second source of truth.
Key capabilities
- Generates API and prose documentation from a module file, package directory, or import path with no special configuration.
- Supports common docstring formats including Markdown, numpydoc, and Google-style docstrings.
- Renders LaTeX math and supports some reStructuredText directives.
- Reads PEP 484 and PEP 526 type annotations.
- Respects
__all__ when it is present, and inherits docstrings for overridden class members when they are unspecified.
- Documents module, class, and instance variables by traversing abstract syntax trees.
- Automatically cross-links referenced identifiers, and allows docstring generation to be overridden through a module-level
__pdoc__ dictionary.
- Provides templates that can be customized and extended, plus a built-in development web server for near-instant previews.
Who uses it and how
- Library maintainers publish generated HTML API references for their packages, since pdoc's own documentation is produced this way.
- Developers preview rendered docstrings locally through the built-in development web server while writing documentation.
- Teams with existing Markdown, numpydoc, or Google-style docstrings generate output without converting their comment style first.
- Projects that annotate code with PEP 484 or PEP 526 types get those annotations reflected in the rendered output.
- Projects needing to hide or reshape specific entries use the
__pdoc__ dictionary to override what is documented.
- Projects with non-standard presentation needs customize the templates rather than replacing the generator.
Getting started
Install with pip install pdoc3, then run pdoc your_project against a module file, package directory, or import path. Additional command-line switches are listed in pdoc --help, and the project documentation covers further usage examples.
When to use it — and when not
Use pdoc when a Python project already carries usable docstrings and wants readable HTML output without adopting a separate documentation format or an elaborate build configuration. A self-hoster operates nothing beyond a Python environment: the tool emits static HTML, and the development web server is built in
