如何 link 到 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.

我希望 link 指向 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 <<a href="http://pythonhosted.org/pyserial/>%60_" rel="noreferrer">http://pythonhosted.org/pyserial/>`_</a> 替换 :ref:，但我真的很想通过 intersphinx 引用该页面，以避免损坏 link下线。

我在 Anaconda 的 Python 3.6.2 上使用 sphinx 1.6.3。我并不过分依赖我正在尝试 link 的图书馆。我怀疑答案不会真的与图书馆联系在一起。

如果有任何问题，对 pyserial 文档的常规引用工作得很好。例如 :py:class:`serial.Serial` links 到 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>`
```

最后，给定页面的清单中可能不存在一些所需的目标。，使用以下内容：

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

出现了所有 API 个对象，这就是为什么您可以 link 那些对象，但只出现了有限数量的其他对象：

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 links。其他作者会很感激。

Answer 2

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

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

另一件需要注意的事情是 pyserial 文档应该 linked 到 https://pyserial.readthedocs.io/en/latest/, not https://pythonhosted.org/pyserial/，就像我一直在做的那样。

如何 link 到 intersphinx 中的根页面

How to link to root page in intersphinx

python

restructuredtext

python-sphinx