How to link to root page in intersphinx

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.

Solution

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

Configure the project to use intersphinx.
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...
```
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>`
```

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.