如何链接到intersphinx中的根页面 [英] How to link to root page in intersphinx

问题描述

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

I have enabled sphinx.ext.intersphinx in my project and added the following configuration:

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

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

I have the following in my index.rst:

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

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

I would like the link to point to http://pythonhosted.org/pyserial/, the root URL in intersphinx_mapping, but I don't know what ??? should be.

如果我执行 :ref:`pyserial` 或 :ref:`pyserial <pyserial>`，我会得到 WARNING: undefined label: pyserial (如果链接没有标题，则标签必须位于节标题之前)

If I do :ref:`pyserial` or :ref:`pyserial <pyserial>`, I get WARNING: undefined label: pyserial (if the link has no caption the label must precede a section header)

如果我执行 :ref:`pyserial <>` 我得到 WARNING: undefined label:(如果链接没有标题，标签必须位于节标题之前)

If I do :ref:`pyserial <>` I get WARNING: undefined label: (if the link has no caption the label must precede a section header)

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

I can replace the :ref: with `pyserial <http://pythonhosted.org/pyserial/>`_, but I would really like to reference the page via intersphinx, to avoid broken links down the line.

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

I am using sphinx 1.6.3 on Python 3.6.2 in Anaconda. I am not overly hung on the library I am trying to link to. I suspect that the answer will not really be tied to a library.

如果有任何关系，对 pyserial 文档的常规引用工作得很好.例如 :py:class:`serial.Serial` 链接到 https://pythonhosted.org/pyserial/pyserial_api.html#serial.Serial.

If it matters any, the regular references to the pyserial docs work just fine. For example :py:class:`serial.Serial` links to https://pythonhosted.org/pyserial/pyserial_api.html#serial.Serial.

推荐答案

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

You've already got the following requirements satisfied. It's the last item that is a common source of frustration.

1. 配置项目以使用 intersphinx.

远程文档使用 Sphinx，实际上有一个名为 objects.inv 的清单文件.当运行 sphinx-build 时，日志条目应该是这样的:

The remote documentation uses Sphinx and does in fact have an inventory file named objects.inv. When running sphinx-build, log entries should be something like this:

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

使用 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 对象都会出现，这就是为什么您可以链接到这些对象，但仅存在有限数量的其他对象:

All the API objects appear, which is why you can link to those, but only a limited number of other objects are present:

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

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

The lack of arbitrary labels is a common annoyance for authors.

您还可以检查项目的目标资源，在这种情况下，没有像 .. _my-reference-label:.

You can also check the project's reST source for targets and in this case, there are no reference labels like .. _my-reference-label:.

要解决此问题，您可以使用任意目标之一:

To resolve this issue, you could either use one of the arbitrary targets:

:ref:`pyserial <pyserial:genindex>`

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

...or better yet submit a pull request to the project where you provide labels for at least the index page, wait for its acceptance, then use that for intersphinx links. Other authors would appreciate it.

这篇关于如何链接到intersphinx中的根页面的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！