Pydoctor

25.10.1 · active · verified Thu Apr 16

Pydoctor is a standalone API documentation generator that works by static analysis. It was primarily written to replace epydoc for the Twisted project, especially due to epydoc's difficulties with `zope.interface`. It aims to provide comprehensive API documentation for Python projects, supporting various docstring formats like epytext, reStructuredText, Google, and Numpy styles. The current version is 25.10.1 and it is actively maintained.

Common errors

```
Pydoctor crashed with traceback
```
cause A runtime error occurred during static analysis or HTML generation. This corresponds to pydoctor's exit code 1.

fix Enable verbose logging with `-v` (or multiple `-vvv`) to get more details. Check for issues in the source code or docstring parsing. Consult the full traceback for the specific error location.
```
Error: Source directory lacks __init__.py
```
cause Prior to pydoctor 25.4.0, pydoctor expected source directories to be traditional packages with an `__init__.py` file. It did not fully support implicit native namespace packages (PEP 420).

fix Upgrade pydoctor to version 25.4.0 or newer to support implicit native namespace packages (PEP 420). Alternatively, ensure that the source directories being documented are valid Python packages with an `__init__.py` file, or explicitly configure them.
```
Error 'Template folder do not exist or is not a directory'
```
cause Pydoctor could not find the specified custom template directory, or the path provided was not a directory.

fix Verify the path provided to the `--template-dir` option (or its equivalent in a config file) is correct and points to an existing directory containing valid template files.
```
Pydoctor fails to find Python objects or resolve links correctly.
```
cause Pydoctor's static analysis might struggle with complex import structures, aliasing, or the project's base directory not matching the current working directory.

fix Specify the project's base directory using `--project-base-dir` for accurate source link computation. Use `--add-package` or `--add-module` explicitly, and ensure all relevant source code is discoverable. For module/package name collisions, better messages are triggered in newer versions.

Warnings

breaking Pydoctor regularly drops support for older Python versions. For example, pydoctor 24.11 dropped Python 3.7, and pydoctor 25.4 dropped Python 3.8. Always check the `requires_python` metadata for compatibility.
Fix: Ensure your Python environment meets the minimum `requires_python` version specified on PyPI (currently >=3.9 for 25.10.1).
gotcha The `--html-viewsource-base` argument, used for linking to source code, should point to a stable Git tag or commit SHA, not a mutable branch (e.g., `master`/`main`). Using a branch can lead to broken source links due to line number mismatches as the code evolves.
Fix: Configure `--html-viewsource-base` with a static reference, such as `https://github.com/your-org/your-repo/tree/v1.2.3` or `https://github.com/your-org/your-repo/tree/COMMIT_SHA`.
breaking The `--html-write-function-pages` option, which generated individual HTML files for functions and methods, was removed in pydoctor 21.2.0.
Fix: Instead of `--html-write-function-pages`, utilize the generated Intersphinx inventory (`objects.inv`) for deep-linking to specific functions or methods in your documentation.
gotcha Pydoctor's exit codes can be non-zero even if HTML output is successfully generated. Exit code `1` indicates a crash, `2` for malformatted docstrings, and `3` if warnings are treated as errors via `--warnings-as-errors`.
Fix: Interpret exit codes carefully in CI/CD pipelines. A non-zero exit code doesn't always mean a critical failure of documentation generation, but may indicate docstring quality issues. Use `--warnings-as-errors` if strict docstring formatting is required.

Install

pip install pydoctor Install latest version

Quickstart

Pydoctor is primarily a command-line interface (CLI) tool. This quickstart demonstrates how to create a minimal Python project and generate its API documentation using the `pydoctor` command-line utility. The `--html-output` option specifies the output directory, and the positional arguments are the paths to the Python source to be documented.

# 1. Create a dummy Python package/module
mkdir -p my_project/src/my_lib
echo """"""A simple library.""""" > my_project/src/my_lib/__init__.py
echo """"""A simple module.
def greet(name: str) -> str:
    """Greets the given name.

    :param name: The name to greet.
    :type name: str
    :return: A greeting message.
    :rtype: str
    """
    return f'Hello, {name}!'
""" > my_project/src/my_lib/greeting.py

# 2. Run pydoctor to generate documentation
cd my_project
pydoctor --project-name="My Project API" \
         --project-version="1.0.0" \
         --html-output=docs/api \
         src/my_lib

# 3. View the generated documentation (e.g., open docs/api/index.html)

view raw JSON →