pydoctor

library25.10.1pypypiunverified

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.

testing data serialization

pip install pydoctor

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PYDOCTOR

pydoctor

testingpythonv25.10.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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)

pydoctor --version

Debug

Known issues

breakingPydoctor 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).

affects: >=24.11

gotchaThe `--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`.

affects: All versions

breakingThe `--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.

affects: >=21.2.0

gotchaPydoctor'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.

affects: All versions

Errors

Common errors & fixes

Pydoctor crashed with traceback

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

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'

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.

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.

Upgrade

Version history

25.10.1latest on PyPI · released Sep 29, 2025

Audit

Dependencies

PythonrequiredRequires Python 3.9 or higher.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/twisted/pydoctor ↗

packagehttps://pypi.org/project/pydoctor/ ↗

docshttps://pydoctor.readthedocs.io/ ↗