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.