如何在 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)

我可以将:ref: 替换为`pyserial <@987654321@，但我真的很想通过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

根据@StevePiercy 的建议，我将PR#261 提交给pyserial。由于 PR 被接受，您现在可以使用 welcome 标签链接到根文档。类似的东西

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

另外需要注意的是，pyserial 文档应该链接到https://pyserial.readthedocs.io/en/latest/，而不是我一直在做的https://pythonhosted.org/pyserial/。

Answer 2

您已满足以下要求。这是最后一个常见的挫折源。

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 项目的语法如下，就像任何 cross-referencing link：

   :role_name:`title <target>`
   

   所以在你的情况下：

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

4. 最后，给定页面的清单中可能不存在一些所需的目标。 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 链接。其他作者将不胜感激。