How to link to root page in intersphinx

Question

I have enabled sphinx.ext.intersphinx in my project and added the following configuration:

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    'pyserial': ('https://pythonhosted.org/pyserial/', None),
}

I have the following in my index.rst:

This project depends on the :ref:`pyserial <pyserial:???>` library.

I would like the link to point to http://pythonhosted.org/pyserial/, the root URL in intersphinx_mapping, but I don't know what ??? should be.

If I do :ref:`pyserial` or :ref:`pyserial <pyserial>`, I get WARNING: undefined label: pyserial (if the link has no caption the label must precede a section header)

If I do :ref:`pyserial <>` I get WARNING: undefined label: (if the link has no caption the label must precede a section header)

I can replace the :ref: with `pyserial <http://pythonhosted.org/pyserial/>`_, but I would really like to reference the page via intersphinx, to avoid broken links down the line.

I am using sphinx 1.6.3 on Python 3.6.2 in Anaconda. I am not overly hung on the library I am trying to link to. I suspect that the answer will not really be tied to a library.

If it matters any, the regular references to the pyserial docs work just fine. For example :py:class:`serial.Serial` links to https://pythonhosted.org/pyserial/pyserial_api.html#serial.Serial.

Answer 1

You've already got the following requirements satisfied. It's the last item that is a common source of frustration.

1. Configure the project to use intersphinx.

2. The remote documentation uses Sphinx and does in fact have an inventory file named objects.inv. When running sphinx-build, log entries should be something like this:

   loading intersphinx inventory from https://docs.python.org/3/objects.inv...
   loading intersphinx inventory from https://pythonhosted.org/pyserial/objects.inv...
   

3. The syntax for Python projects using intersphinx is the following, just like any cross-referencing link:

   :role_name:`title <target>`
   

   So in your case:

   :ref:`pyserial <pyserial:reference-label-name>`
   

4. Finally, some desired targets might not exist in the inventory for a given page. This answer shows how to see all intersphinx targets, using the following:

   python -m sphinx.ext.intersphinx 'https://pythonhosted.org/pyserial/objects.inv'
   

   All the API objects appear, which is why you can link to those, but only a limited number of other objects are present:

   std:label
           examples                                 Examples                                : examples.html#examples
           genindex                                 Index                                   : genindex.html#
           miniterm                                 serial.tools.miniterm                   : tools.html#miniterm
           modindex                                 Module Index                            : py-modindex.html#
           search                                   Search Page                             : search.html#
           urls                                     URL Handlers                            : url_handlers.html#urls
   

   The lack of arbitrary labels is a common annoyance for authors.

   You can also check the project's reST source for targets and in this case, there are no reference labels like .. _my-reference-label:.

To resolve this issue, you could either use one of the arbitrary targets:

:ref:`pyserial <pyserial:genindex>`

...or better yet submit a pull request to the project where you provide labels for at least the index page, wait for its acceptance, then use that for intersphinx links. Other authors would appreciate it.

Answer 2

Based on the suggestion by @StevePiercy, I submitted PR#261 to pyserial. Since the PR was accepted, you can now link to the root docs using the welcome label. Something like

This project depends on the :ref:`pyserial <pyserial:welcome>` library.

The other thing to note is that the pyserial docs should be linked to https://pyserial.readthedocs.io/en/latest/, not https://pythonhosted.org/pyserial/ as I have been doing.