2

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Jeff G
  • 4,470
  • 2
  • 41
  • 76
  • Does it work if you use `:any:` instead of `:ref:`? – mzjn May 29 '18 at 17:57
  • Sadly, no. I get the same warning, but with `:ref:` replaced by `:any:`. – Jeff G May 29 '18 at 23:31
  • 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 https://github.com/python/cpython/blob/3.6/Doc/contents.rst). – mzjn May 30 '18 at 07:00
  • I have not tried to create documentation locally. ``:any:`Python ` `` 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 May 30 '18 at 07:09

1 Answers1

2

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.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • This fixes the error I was seeing when trying to use the new syntax for `intersphinx_mapping`, but still doesn't result in a link to the appropriate document. I have upvoted this answer, since it helped me. I also updated the question to reflect the new behavior after applying this fix, since I am still unable to generate a link to the referenced document. – Jeff G May 29 '18 at 17:32
  • Here is the bug report for toctree not supporting intersphinx: https://github.com/sphinx-doc/sphinx/issues/1836 – Josiah Feb 27 '20 at 14:17