CLI Options and Config File

Command line options

API doc generator.

usage: pydoctor [options] SOURCEPATH...

Positional Arguments

SOURCEPATH

Path to python modules/packages to document.

Named Arguments

-c, --config

Load config from this file (any command lineoptions override settings from the file).

--project-name

The project name, shown at the top of each HTML page.

--project-version

The version of the project for which the API docs are generated. Defaults to empty string.

--project-url

The project url, appears in the html if given.

--project-base-dir

Path to the base directory of the project. Source links will be computed based on this value.

--testing

Don’t complain if the run doesn’t have any effects.

--pdb

Like py.test’s –pdb.

--make-html

Produce html output. Enabled by default if options ‘–testing’ or ‘–make-intersphinx’ are not specified.

--make-intersphinx

Produce (only) the objects.inv intersphinx file.

--prepend-package

Pretend that all packages are within this one. Can be used to document part of a package.

--docformat

Possible choices: plaintext, google, epytext, numpy, restructuredtext

Format used for parsing docstrings. Supported values: plaintext, google, epytext, numpy, restructuredtext

--theme

Possible choices: base, readthedocs, classic

The theme to use when building your API documentation.

--template-dir

Directory containing custom HTML templates. Can be repeated.

--privacy

Set the privacy of specific objects when default rules doesn’t fit the use case. Format: ‘<PRIVACY>:<PATTERN>’, where <PRIVACY> can be one of ‘PUBLIC’, ‘PRIVATE’ or ‘HIDDEN’ (case insensitive), and <PATTERN> is fnmatch-like pattern matching objects fullName. Pattern added last have priority over a pattern added before, but an exact match wins over a fnmatch. Can be repeated.

--html-subject

The fullName of objects to generate API docs for (generates everything by default).

--html-summary-pages

Only generate the summary pages.

--html-output

Directory to save HTML files to (default ‘apidocs’)

--html-writer

Dotted name of HTML writer class to use (default ‘pydoctor.templatewriter.TemplateWriter’).

--html-viewsource-base

This should be the path to the trac browser for the top of the svn checkout we are documenting part of.

--html-viewsource-template

A format string used to generate the source link of documented objects. The default behaviour auto detects most common providers like Github, Bitbucket, GitLab or SourceForge. But in some cases you might have to override the template string, for instance to make it work with git-web, use: –html-viewsource-template=”{mod_source_href}#n{lineno}”

--buildtime

Use the specified build time over the current time. Format: YYYY-mm-dd HH:MM:SS

--process-types

Process the ‘type’ and ‘rtype’ fields, add links and inline markup automatically. This settings should not be enabled when using google or numpy docformat because the types are always processed by default.

--warnings-as-errors, -W

Return exit code 3 on warnings.

--verbose, -v

Be noisier. Can be repeated for more noise.

--quiet, -q

Be quieter.

--introspect-c-modules

Import and introspect any C modules found.

--intersphinx

Use Sphinx objects inventory to generate links to external documentation. Can be repeated.

--disable-intersphinx-cache

Disable Intersphinx cache.

--intersphinx-cache-path

Where to cache intersphinx objects.inv files.

--clear-intersphinx-cache

Clear the Intersphinx cache specified by –intersphinx-cache-path.

--intersphinx-cache-max-age

The maximum age of any entry in the cache. Of the format <int><unit> where <unit> is one of s (seconds), m (minutes), h (hours), d (days), w (weeks).

--pyval-repr-maxlines

Maxinum number of lines for a constant value representation. Use 0 for unlimited.

--pyval-repr-linelen

Maxinum number of caracters for a constant value representation line. Use 0 for unlimited.

--sidebar-expand-depth

How many nested modules and classes should be expandable, first level is always expanded, nested levels can expand/collapse. Value should be 1 or greater. (default: 1)

--sidebar-toc-depth

How many nested titles should be listed in the docstring TOC (default: 6)

--no-sidebar

Do not generate the sidebar at all.

--system-class

A dotted name of the class to use to make a system.

-V, --version

show program’s version number and exit

Configuration file

All arguments can also be set in a config file.

Repeatable arguments must be defined as list.

Positional arguments can be set with option add-package.

By convention, the config file resides on the root of your repository.

Pydoctor automatically integrates with common project files ./pyproject.toml or ./setup.cfg and loads file ./pydoctor.ini if if exists. The configuration parser supports TOML and INI formats.

Note

No path processing is done to determine the project root directory, pydoctor only looks at the current working directory. You can set a different config file path with option --config, this is necessary to load project configuration files from Sphinx’s conf.py.

pydoctor.ini

Declaring section [pydoctor] is required.

[pydoctor]
add-package =
    src/mylib
intersphinx =
    https://docs.python.org/3/objects.inv
    https://twistedmatrix.com/documents/current/api/objects.inv
docformat = restructuredtext
verbose = 1
warnings-as-errors = true
privacy =
    HIDDEN:pydoctor.test
    PUBLIC:pydoctor._configparser

pyproject.toml

pyproject.toml are considered for configuration when they contain a [tool.pydoctor] table. It must use TOML format.

[tool.pydoctor]
add-package = ["src/mylib"]
intersphinx = ["https://docs.python.org/3/objects.inv",
               "https://twistedmatrix.com/documents/current/api/objects.inv"]
docformat = "restructuredtext"
verbose = 1
warnings-as-errors = true
privacy = ["HIDDEN:pydoctor.test",
           "PUBLIC:pydoctor._configparser",]

Note that the config file fragment above is also valid INI format and could be parsed from a setup.cfg file successfully.

setup.cfg

setup.cfg can also be used to hold pydoctor configuration if they have a [tool:pydoctor] section. It must use INI format.

[tool:pydoctor]
add-package =
    src/mylib
intersphinx =
    https://docs.python.org/3/objects.inv
    https://twistedmatrix.com/documents/current/api/objects.inv
docformat = restructuredtext
verbose = 1
warnings-as-errors = true
privacy =
    HIDDEN:pydoctor.test
    PUBLIC:pydoctor._configparser

Note

If an argument is specified in more than one place, then command line values override config file values which override defaults. If more than one config file exists, pydoctor.ini overrides values from pyproject.toml which overrrides setup.cfg. Repeatable options are not merged together, there are overriden as well.

Note

The INI parser behaves like configargparse.ConfigparserConfigFileParser in addition that it converts plain multiline values to list, each non-empty line will be converted to a list item. If for some reason you need newlines in a string value, just tripple quote your string like you would do in python.

Allowed syntax is that for a configparser.ConfigParser with the default options.

Note

Last note: pydoctor has always supported a --config option, but before 2022, the format was undocumentd and rather fragile. This new configuration format breaks compatibility with older config file in three main ways:

• Options names are now the same as argument without the leading -- (e.g project-name and not projectname).

• Define repeatable options with multiline strings or list literals instead of commas separated string.