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}

Similarly, you can link external API documentation from a local directory
with the following configuration option::

    --intersphinx-file=~/projects/myproject/docs/api/objects.inv

This will link to API documentation relative to the file location.
If the API documentation are served online but behind an authentication 
page then the object inventory file will not accessible to pydoctor. In
this case, you can download the inventory file but still link to the
correct internet URL using an optional base URL.

	--intersphinx-file=~/projects/myproject/docs/api/objects.inv::https://sphinx/api


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

__ https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

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 :py:func:`with custom text <twisted:twisted.web.client.urlunparse>` with::

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

Link to elements with default label :py:class:`twisted: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 :py:mod:`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 <https://github.com/twisted/pydoctor/blob/master/docs/source/conf.py>`_
for usage example.