指定指向numpy,scipy和matplotlib的狮身人面像链接的目标



按照在软件包之间设置狮身人面像文档链接的文档,我添加了

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:

在哪里可以找到有关如何在numpyscipymatplotlib中指定:ref::term:目标的说明?


就此而言,我如何链接到狮身人面像本身?添加

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

:ref:`Intersphinx <intersphinx>`

不行。

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

我有一个包含一些intersphinx映射的 Gist,现在包括所有numpyscipymatplotlib。 您应该能够直接在intersphinx_mapping中使用这些条目,在您的conf.py中。如果有人建议将更多条目添加到此列表中,请随时在 Gist 的评论中发布请求。

对于所有这些软件包,根据 fgoudra 的回答,我强烈建议使用sphobjinvobjects.inv文件中搜索每个库。 (完全披露:我是sphobjinv的作者。CLI 接口的suggest模式专门设计用于提供撰写狮身人面像交叉引用所需的信息。


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

:func:`numpy.cross`

其他时候(例如,对于 C 函数),您可以只引用函数的基本名称,但您必须明确指示域,例如:

:c:func:`PyArray_InnerProduct`

在其他时候,您可能必须引用自定义np域,例如:

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

如果不咨询objects.inv,就真的没有办法知道正确的语法是什么。

 

scipynumpy一样高深莫测。通过为各种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:(我很高兴知道为什么)。

最新更新