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

Posted 2023-02-23

【中文标题】为 numpy、scipy 和 matplotlib 的 intersphinx 链接指定目标

【英文标题】：Specifying targets for intersphinx links to numpy, scipy, and matplotlib

【发布时间】：2014-02-27 15:00:21

【问题描述】：

按照在包之间设置 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:s 是什么由软件包支持。

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

---

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

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

和

:ref:`Intersphinx <intersphinx>`

没用。

【问题讨论】：

使用:term:`svg graphics <matplotlib:svg>` 对我来说很好。我无法解释为什么您只能进入索引页面。如果您想链接到 intersphinx 文档页面，请使用模块名称：:mod:`Intersphinx <sphinx.ext.intersphinx>` 。

这个答案展示了如何为文档项目找到可用的 intersphinx 目标：***.com/a/30981554/407651。

您使用的是旧版本的 sphinx 吗？我记得，旧版本只支持引用 identifiers，但不支持 :ref: 和类似的。您是否尝试过像In python you can `open` a file 这样的操作？

How to properly write cross-references to external documentation with intersphinx?的可能重复

我发现sphobjinv 命令行工具对这项任务非常有用。

【参考方案1】：

可以手动指定要查看的库存。例如，如果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 包探索二进制文件并检查您想要的引用在哪里。

这可能无法解决您的问题，但可以帮助调试一些东西。

【参考方案2】：

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

我有一个Gist 和一些intersphinx 映射，现在包括所有numpy、scipy 和matplotlib。您应该能够直接在intersphinx_mapping 中的conf.py 中使用这些条目。如果有人对要添加到此列表的更多条目有任何建议，请随时将请求发布到 Gist 的 cmets。

对于所有这些包，根据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 子包引入大量自定义域使事情变得更加复杂，例如：

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

 

对于matplotlib，看来您总是必须在引用中提供（相当冗长的）完全指定的对象名称，例如：

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

不过，所有matplotlib 代码对象似乎都驻留在默认的py 域中，这在一定程度上简化了事情。

 

对于其中任何一个，如果您无法正确构建链接，我首先会使用通用的:obj: 角色，例如：

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

这将构造一个intersphinx 链接，无论定义特定对象的角色如何，但我认为您仍然必须正确指定任何相关的非默认域。如果引用不能与:obj: 角色一起正常工作，那么对象名称或某处的域中存在错误。检查两个地方的拼写错误。

【参考方案3】：

如果这仍然是一个问题.. 您需要省略 URL 末尾的斜杠：

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.org/stable', None)

【讨论】：

matplotlib 的正确字典条目现在是 'matplotlib': ('http://matplotlib.org/stable', None)。

谢谢。我已相应地对其进行了编辑。

【参考方案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:（我很乐意知道原因）。