How to Link Local Python Help Documents Using Sphinx

Question

How can I get my Sphinx RST file to include a link to the "contents.html" Python help page?

More Details

I have an RST help document (index.rst) in an offline environment. I have downloaded and successfully built the Python documentation using the command make.bat html. I then copied this documentation to C:\Temp\PyDoc.

I then updated my conf.py file to include the following Intersphinx mapping:

intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}

Then, within my index.rst file, I have something like:

Contents:

.. toctree::
   :maxdepth: 1

   :ref:`Python <python:contents>`

The Python link is removed from the resulting documentation with the warning message:

WARNING: toctree contains reference to nonexisting document ':ref:`Python <python:contents>`'

I have verified that the output contains the text:

loading intersphinx inventory from C:/Temp/PyDoc/objects.inv...

I have also verified that the "contents" tag exists within the Python documentation by running:

python -m sphinx.ext.intersphinx "C:/Temp/PyDoc/objects.inv" | findstr contents

Which generates output that includes the line:

contents Python Documentation contents : contents.html

Does anyone know how to reference this external documentation from my RST file?

Sadly, no. I get the same warning, but with :ref: replaced by :any:. — Jeff G
In any case, I would not expect :ref: to work, since that role is used for cross-references to explicit labels such as .. _contents:. The page that you want to link to does not contain any label (see github.com/python/cpython/blob/3.6/Doc/contents.rst). — mzjn
I have not tried to create documentation locally. :any:`Python <python:contents>` works for me if it is a regular inline cross-reference (not a toctree item), using intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}. — mzjn

Steve Piercy Steve Piercy · Accepted Answer · 2018-05-26T07:53:47

In the configuration for intersphinx, the dict's key's value is a tuple, which consists of comma-separated values, not colon-separated.

intersphinx_mapping = {'python': ('C:/Temp/PyDoc', None)}

EDIT

toctree entries need a valid target, which can be a file relative to the current file or absolute as starting from the documentation root where your conf.py resides. Also the target may be an URL. I suspect that the HTML you made is none of the above, so you need to move it to a place where Sphinx can find it.

The syntax should be for documentation, not a Python object, because the page is a table of contents. I did not try this example because I don't have the Python docs downloaded and built, so I doubt it will work.

.. toctree::
    :maxdepth: 1

    :doc:`Python <python:contents>`

Or you can just use the URL (or similar relative or absolute target). This works for me with a fully qualified URL.

.. toctree::
    :maxdepth: 1

    Python <https://docs.python.org/3/contents.html>

Finally you could try an include, but I think that is not what you really want.

How to Link Local Python Help Documents Using Sphinx

1 Answers