Question

按照软件包之间设置Sphinx文档链接的文档，我添加了

intersphinx_mapping = {'python': ('http://docs.python.org/2', None),
                       'numpy': ('http://docs.scipy.org/doc/numpy/', None),
                       'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
                       'matplotlib': ('http://matplotlib.sourceforge.net/', None)}

到我的conf.py，但似乎无法获得除Python本身以外的任何项目的链接。例如

:term:`svg graphics <matplotlib:svg>`

只需将我带到索引页面，而不添加预期的#term-svg锚点，我甚至无法找到scipy的词汇表或弄清楚如何确定:ref: s或:term:由包支持。

我在哪里可以找到有关如何在:ref:，:term:和numpy中指定scipy和matplotlib的目标的说明？

就此而言，我如何链接到Sphinx本身？添加

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None)

和

:ref:`Intersphinx <intersphinx>`

不起作用。

Answer 1

我在哪里可以找到有关如何在:ref:，:term:和numpy中指定scipy和matplotlib的目标的说明？

我有一个Gist，其中包含一些intersphinx映射，现在包含numpy，scipy和matplotlib的所有映射。您应该可以在conf.py内的intersphinx_mapping中直接使用这些条目。如果有人建议将更多条目添加到此列表中，请随时将请求发布到Gist的评论中。

对于所有这些软件包，按fgoudra's answer我强烈建议您使用sphobjinv在objects.inv文件中搜索每个库。（完全披露：我是sphobjinv的作者。）CLI界面的suggest模式专门用于提供组成intersphinx交叉引用所需的信息。

numpy很复杂。有时您需要一个完全限定的名称，例如：

:func:`numpy.cross`

其他时候（例如对于C函数），您只需引用函数的基本名称，但必须明确指出域名，例如：

:c:func:`PyArray_InnerProduct`

有时您可能需要引用自定义np域名，例如：

:np:func:`numpy.ma.append`

如果不咨询objects.inv，就无法知道正确的语法是什么。

scipy与numpy大致相同。通过为各种scipy子包引入众多自定义域，事情变得更加复杂，例如：< / p>

:scipy-optimize:func:`scipy.integrate.newton_cotes`

对于matplotlib，，您似乎总是必须在引用中提供（非常详细的）完全指定的对象名称，例如：

:meth:`matplotlib.axes.Axes.plot`

所有matplotlib代码对象似乎都位于默认的py域中，但这有点简化了事情。

对于其中任何一种，如果您在获取正确构建的链接时遇到问题，我首先要回到的是使用通用:obj:角色，例如：

:obj:`matplotlib.axes.Axes.plot`

这将构建intersphinx链接，无论特定对象的定义角色如何，但我认为您仍需要正确指定任何相关的非默认域。如果引用在:obj:角色中无法正常工作，则对象名称或域中存在错误。检查两个地方的拼写错误。

Answer 2

可以手动指定要查看的库存。例如，如果intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None) 不起作用，您可以随时下载库存并手动将其附加到映射（例如从http://sphinx-doc.org/objects.inv下载，将二进制文件保存在您的文档中并在映射中附加它的路径;这将提供如下内容：

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', ('objects.inv', ), )

要验证清单中是否存在引用，您可以使用sphobjinv python包探索二进制文件，并检查所需的引用位置。

这可能不是您的问题的解决方案，但可以帮助调试一些事情。

Answer 3

如果这仍然是一个问题。您需要在网址末尾省略斜杠：

intersphinx_mapping = {'python': ('http://docs.python.org/2', None),
                       'numpy': ('http://docs.scipy.org/doc/numpy', None),
                       'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
                       'matplotlib': ('http://matplotlib.sourceforge.net', None)}

Answer 4

了解交叉引用的另一种方法是使用sphobjinv模块。

您可以搜索本地或什至远程清单文件（具有模糊匹配）。例如，使用scipy：

$ sphobjinv suggest -t 90 -u https://docs.scipy.org/doc/scipy/reference/objects.inv "signal.convolve2d"

Remote inventory found.

:py:function:`scipy.signal.convolve2d`
:std:doc:`generated/scipy.signal.convolve2d`

请注意，您可能需要使用:py:func:而不是:py:function:（我很高兴知道原因）。

为numpy，scipy和matplotlib指定intersphinx链接的目标

4 个答案: