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

How to link to root page in intersphinx

2 Answers