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

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 anchor ，我什至无法找到 scipy 的词汇表或弄清楚如何确定包支持哪些 :ref:s 或 :term:s。

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

---

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

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

和

:ref:`Intersphinx <intersphinx>`

没用。

Answer 1

Where can I find instructions on how to specify targets for :ref:s and :term:s in numpy, scipy, and matplotlib?

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

对于所有这些软件包，根据 fgoudra's answer我强烈推荐使用 sphobjinv在 objects.inv 文件中搜索每个库。 (完全披露:我是 sphobjinv 的作者。)suggest CLI 界面的模式专门用于提供编写 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: 角色一起正常工作，那么对象名称或某处的域中存在错误。检查两个地方的拼写错误。