Question

我在项目中启用了sphinx.ext.intersphinx并添加了以下配置：

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

我的index.rst中有以下内容：

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

我希望该链接指向http://pythonhosted.org/pyserial/，intersphinx_mapping中的根网址，但我不知道???应该是什么。

如果我:ref:`pyserial`或:ref:`pyserial <pyserial>`，我会WARNING: undefined label: pyserial (if the link has no caption the label must precede a section header)

如果我:ref:`pyserial <>`，我会WARNING: undefined label: (if the link has no caption the label must precede a section header)

我可以用:ref:替换`pyserial <http://pythonhosted.org/pyserial/>`_，但我真的想通过intersphinx引用该页面，以避免链接断开。

我在Anaconda的Python 3.6.2上使用sphinx 1.6.3。我并没有过度依赖我试图链接到的图书馆。我怀疑答案不会真正与图书馆联系在一起。

如果重要的是，对pyserial文档的常规引用工作正常。例如，:py:class:`serial.Serial`链接到https://pythonhosted.org/pyserial/pyserial_api.html#serial.Serial。

Answer 1

您已满足以下要求。这是最后一个令人沮丧的常见问题。

将项目配置为使用intersphinx。

远程文档使用Sphinx，实际上有一个名为objects.inv的清单文件。运行sphinx-build时，日志条目应如下所示：

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

使用intersphinx的Python项目的语法如下，就像任何cross-referencing link一样：
```
:role_name:`title <target>`
```
所以在你的情况下：
```
:ref:`pyserial <pyserial:reference-label-name>`
```

最后，给定页面的库存中可能不存在某些所需目标。 This answer shows how to see all intersphinx targets，使用以下内容：

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

显示所有API对象，这就是您可以链接到这些对象的原因，但只存在有限数量的其他对象：

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

缺乏任意标签是作者常见的烦恼。

您还可以check the project's reST source for targets，在这种情况下，没有像.. _my-reference-label:这样的参考标签。

要解决此问题，您可以使用其中一个任意目标：

:ref:`pyserial <pyserial:genindex>`

...或者更好的是向项目提交拉取请求，在该项目中，您至少为索引页面提供标签，等待其接受，然后将其用于intersphinx链接。其他作者会很感激。

Answer 2

根据@StevePiercy的建议，我向pyserial提交了PR#261。由于PR已被接受，您现在可以使用welcome标签链接到根文档。像

这样的东西

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

另外需要注意的是，pyserial文档应该与https://pyserial.readthedocs.io/en/latest/相关联，而不是像我一直那样https://pythonhosted.org/pyserial/。

如何链接到intersphinx中的根页面

2 个答案: