如何链接到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/,根URL intersphinx_mapping,但我不知道???应该是什么.

如果我做的: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:with ,但我真的想通过intersphinx引用页面,以避免断开链接.`pyserial <http://pythonhosted.org/pyserial/>`_

我在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

您已满足以下要求.这是最后一个令人沮丧的常见问题.

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>`
   

4. 最后,给定页面的库存中可能不存在某些所需目标.此答案显示如何使用以下内容查看所有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>`

...或更好,但提交pull请求,你至少索引页面提供标签的项目,等待其接受,然后利用它来进行intersphinx链接.其他作者会很感激.