CLI Options and Config File

Command line options

API doc generator.

usage: pydoctor [options] SOURCEPATH...

Positional Arguments


Path to python modules/packages to document.

Named Arguments

-c, --config

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


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


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


The project url, appears in the html if given.


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


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


Like py.test’s –pdb.


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


Produce (only) the objects.inv intersphinx file.


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


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

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


Possible choices: base, readthedocs, classic

The theme to use when building your API documentation.


Directory containing custom HTML templates. Can be repeated.


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.


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


Only generate the summary pages.


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


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


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


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}”


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


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.


Import and introspect any C modules found.


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


Disable Intersphinx cache.


Where to cache intersphinx objects.inv files.


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


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


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


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


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)


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


Do not generate the sidebar at all.


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


Possible choices: alphabetical, source

Presentation order of class members. (default: alphabetical)


Possible choices: alphabetical, source

Presentation order of module/package members. (default: alphabetical)

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


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


Declaring section [pydoctor] is required.

add-package =
intersphinx =
docformat = restructuredtext
verbose = 1
warnings-as-errors = true
privacy =


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

add-package = ["src/mylib"]
intersphinx = ["",
docformat = "restructuredtext"
verbose = 1
warnings-as-errors = true
privacy = ["HIDDEN:pydoctor.test",

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


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

add-package =
intersphinx =
docformat = restructuredtext
verbose = 1
warnings-as-errors = true
privacy =


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.


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.


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.