按照在软件包之间设置狮身人面像文档链接的文档,我添加了
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:
或:term:
。
在哪里可以找到有关如何在numpy
、scipy
和matplotlib
中指定:ref:
和:term:
目标的说明?
就此而言,我如何链接到狮身人面像本身?添加
intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None)
和
:ref:`Intersphinx <intersphinx>`
不行。
在哪里可以找到有关如何在
numpy
、scipy
和matplotlib
中为:ref:
s 和:term:
s 指定目标的说明?
我有一个包含一些intersphinx
映射的 Gist,现在包括所有numpy
、scipy
和matplotlib
。 您应该能够直接在intersphinx_mapping
中使用这些条目,在您的conf.py
中。如果有人建议将更多条目添加到此列表中,请随时在 Gist 的评论中发布请求。
对于所有这些软件包,根据 fgoudra 的回答,我强烈建议使用sphobjinv
在objects.inv
文件中搜索每个库。 (完全披露:我是sphobjinv
的作者。CLI 接口的suggest
模式专门设计用于提供撰写狮身人面像交叉引用所需的信息。
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:
角色正常工作,则对象名称或某处的域中存在错误。检查两个地方是否有拼写错误。
如果这仍然是一个问题.. 您需要省略 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)}
可以手动指定要查看的清单。例如,如果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 包探索二进制文件,并检查您想要的引用在哪里。
这可能不是您问题的解决方案,但可以帮助调试某些内容。
知道如何进行交叉引用的另一种方法是使用 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:
(我很高兴知道为什么)。