为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锚点,我甚至无法找到词汇表scipy或找出如何确定包所支持的:ref:s或:term:s.

我在哪里可以找到如何指定目标指令:ref:S和:term:S IN numpy,scipy和matplotlib？

---

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

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

和

:ref:`Intersphinx <intersphinx>`

不起作用.

Answer 1

我在哪里可以找到如何指定目标指令:ref:S和:term:S IN numpy,scipy和matplotlib？

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

对于所有这些软件包,根据fgoudra的回答,我强烈建议您使用sphobjinv在objects.inv文件中搜索每个库.(完全披露:我是作者sphobjinv.)suggestCLI界面的模式专门用于提供组成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:角色不能正常工作,那么对象名称或域中的某个地方就会出错.检查两个地方的拼写错误.

Answer 2

如果这仍然是一个问题..您需要省略 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)}

Answer 3

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

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