Sphinx Integration

Sphinx object inventories can be used to create links in both ways between documentation generated by pydoctor and by Sphinx.

Linking from pydoctor to external API docs

It can link to external API documentation using a Sphinx objects inventory with the following cumulative configuration option:

--intersphinx=https://docs.python.org/3/objects.inv

Note

The URL must point to the the objects.inv.

Then, your interpreted text, with backticks (`) using restructuredtext and with L{} tag using epytext, will be linked to the Python element. Example:

`datetime.datetime`
L{datetime.datetime}

Simple as that!

Linking from Sphinx to your pydoctor API docs

pydoctor’s HTML generator will also generate a Sphinx objects inventory that can be used with the following mapping:

• packages, modules -> :py:mod:

• classes -> :py:class:

• functions -> :py:func:

• methods -> :py:meth:

• attributes -> :py:attr:

You can use this mapping in Sphinx via the Intersphinx extension.

For an up to date lists of API links, run pydoctor before building the Sphinx documentation.

You can use the --make-intersphinx option to only generate the object inventory file.

You will then reference this file inside the Sphinx intersphinx_mapping.

Note that relative paths are relative to the Sphinx source directory. You might need to exit the source and reference the build directory:

intersphinx_mapping = {
    'twisted': ('https://twistedmatrix.com/documents/current/api/', '../../build/apidocs/objects.inv'),
}

Link to elements with custom text with:

:py:func:`with custom text <twisted:twisted.web.client.urlunparse>`

Link to elements with default label twisted.web.client.HTTPDownloader with:

:py:class:`twisted:twisted.web.client.HTTPDownloader`

Building pydoctor together with Sphinx HTML build

When running pydoctor with HTML generation it will generate a set of static HTML files that can be used any HTTP server.

Under some circumstances (ex Read The Docs) you might want to trigger the pydoctor API docs build together with the Sphinx build.

This can be done by using the pydoctor.sphinx_ext.build_apidocs extension.

Inside your Sphinx conf.py file enable and configure the extension in this way:

extensions.append("pydoctor.sphinx_ext.build_apidocs")

pydoctor_args = [
    '--project-name=YOUR-PROJECT-NAME',
    '--project-version=YOUR-PUBLIC-VERSION',
    '--project-url=YOUR-PROJECT-HOME-URL',
    '--docformat=epytext',
    '--intersphinx=https://docs.python.org/3/objects.inv',
    '--html-viewsource-base=https://github.com/ORG/REPO/tree/default',
    '--html-output={outdir}/api',
    '--project-base-dir=path/to/source/code',
    'path/to/source/code/package1'
    ]

pydoctor_url_path = '/en/{rtd_version}/api/'

You can pass almost any argument to pydoctor_args in the same way you call pydoctor from the command line.

You don’t need to pass the --make-html, --make-intersphinx or --quiet arguments. The extension will add them automatically.

The pydoctor_url_path is an URL path, relative to your public API documentation site. {rtd_version} will be replaced with the Read The Docs version (stable , latest, tag name). You only need to define this argument if you need to have Intersphinx links from your Sphinx narrative documentation to your pydoctor API documentation.

As a hack to integrate the pydoctor API docs index.html with the Sphinx TOC and document reference, you can create an index.rst at the location where the pydoctor index.html is hosted. The Sphinx index.html will be generated during the Sphinx build process and later overwritten by the pydoctor build process.

It is possible to call pydoctor multiple times (with different arguments) as part of the same build process. For this you need to define pydoctor_args as a dict. The key is the human readable build name and the value for each dict member is the list of arguments. See pydoctor’s own conf.py for usage example.