如何在intersphinx中链接到根页面

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中的根URL，但我不知道???应该填什么。

如果我使用: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)。

我可以用`pyserial <http://pythonhosted.org/pyserial/>`_替换:ref:，但我真的想通过intersphinx引用页面，以避免将来出现链接失效的情况。

我正在使用Anaconda中的Python 3.6.2上的sphinx 1.6.3。我并不特别关注我要链接的库。我认为答案与库无关。

如果有影响的话，对pyserial文档的常规引用完全正常。例如，:py:class:`serial.Serial`链接到https://pythonhosted.org/pyserial/pyserial_api.html#serial.Serial。

- Mad Physicist

Answer 1

你已经满足了以下要求。最后一项通常是导致挫败的共同原因。

1. 配置项目以使用 intersphinx。

2. 远程文档使用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...
   

3. 使用intersphinx的Python项目的语法与任何交叉引用链接一样，如下所示:

:role_name:`title <target>`

所以在你的情况下：

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

最后，对于某个页面，可能不存在所需的目标。 这个答案展示了如何查看所有intersphinx目标，使用以下内容：

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

对于作者来说，缺乏任意标签是一个常见的烦恼。

您也可以查看项目的reST源文件以获取目标，在这种情况下，没有像.. _my-reference-label:这样的参考标签。

为了解决这个问题，您可以使用任意目标之一：

:ref:`pyserial <pyserial:genindex>`

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

- Steve Piercy

---

对我来说，这听起来是一个合理的解决方案。我会继续提交那个PR。 - Mad Physicist

只是出于好奇，我如何区分python和pyserial文档中的“示例”标签？ - Mad Physicist

在目标部分尝试使用<python:examples>和<pyserial:examples>，因为我无法在注释中使用文字反引号。 - Steve Piercy

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/。

- Mad Physicist