python - 如何链接到intersphinx中的根页面

我在我的项目中启用了 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 <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 。

最佳答案

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

配置项目以使用 intersphinx 。

远程文档使用Sphinx，实际上确实有一个名为objects.inv的 list 文件。运行 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>`

最后，给定页面的 list 中可能不存在某些所需的目标。 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 链接。其他作者会很感激的。

关于python - 如何链接到intersphinx中的根页面，我们在Stack Overflow上找到一个类似的问题：https://stackoverflow.com/questions/45699577/

PySerial

python - 如何链接到intersphinx中的根页面