Quick Start

Installation

Pydoctor can be installed from PyPI:

$ pip install -U pydoctor

For Debian and derivatives, pydoctor can be installed with apt:

$ sudo apt install pydoctor

Example

The following example uses most common options to generate pydoctor’s own API docs under the docs/api folder. It will add a link to the project website in the header of each page, show a link to its source code beside every documented object and resolve links to Python standard library objects.

The result looks like this.

pydoctor \
    --project-name=pydoctor \
    --project-version=1.2.0 \
    --project-url=https://github.com/twisted/pydoctor/ \
    --html-viewsource-base=https://github.com/twisted/pydoctor/tree/20.7.2 \
    --make-html \
    --html-output=docs/api \
    --project-base-dir="." \
    --docformat=epytext \
    --intersphinx=https://docs.python.org/3/objects.inv \
    ./pydoctor

Note

This example assume that you have cloned and installed pydoctor and you are running the pydoctor build from Unix and the current directory is the root folder of the Python project.

Tip

First run pydoctor with --docformat=plaintext to focus on eventual python code parsing errors. Then, enable docstring parsing by selecting another docformat.

Warning

The --html-viewsource-base argument should point to a tag or a commit SHA rather than a branch since line numbers are not going to match otherwise when commits are added to the branch after the documentation has been published.

Publish your documentation

Output files are static HTML pages which require no extra server-side support.

Here is a GitHub Action example to automatically publish your API documentation to your default GitHub Pages website.