指定指向 numpy、scipy 和 matplotlib 的 intersphinx 链接的目标 [英] Specifying targets for intersphinx links to numpy, scipy, and matplotlib

问题描述

按照在包之间设置 Sphinx 文档链接的文档，我添加了

Following the documentation for setting up Sphinx documentation links between packages, I have added

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 本身之外的任何项目的链接.例如

to my conf.py, but can't seem to get links to any project other than Python itself to work. For example

:term:`svg graphics <matplotlib:svg>`

只是将我带到索引页面，而不添加预期的 #term-svg 锚点，我什至无法找到 scipy 的词汇表或弄清楚如何确定软件包支持哪些:ref: s或:term: s.

just takes me to the index page, without adding the expected #term-svg anchor, and I can't even locate the glossary for scipy or figure out how to determine what :ref:s or :term:s are supported by a package.

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

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

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

For that matter, how do I link to Sphinx itself? Adding

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

和

:ref:`Intersphinx <intersphinx>`

不起作用.

推荐答案

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

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的评论中.

I have a Gist with a handful of intersphinx mappings, which now includes all of numpy, scipy and matplotlib. You should be able to use these entries directly in intersphinx_mapping, within your conf.py. If anyone has suggestions for further entries to be added to this list, please feel free to post requests into the comments of the Gist.

对于所有这些软件包，每个 fgoudra的答案我强烈建议使用

For all of these packages, per fgoudra's answer I highly recommend using sphobjinv to search within the objects.inv file for each library. (Full disclosure: I am the author of sphobjinv.) The suggest mode of the CLI interface is specifically designed to provide the information needed to compose intersphinx cross-references.

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

numpy is complicated. Sometimes you need a fully-qualified name, e.g.:

:func:`numpy.cross`

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

Other times (for C functions, for example) you can just reference the function's base name BUT you have to explicitly indicate the domain, e.g.:

:c:func:`PyArray_InnerProduct`

但有时您可能需要引用自定义 np 域，例如:

Yet other times you may have to reference the custom np domain, e.g.:

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

如果不查阅 objects.inv，真的无法知道正确的语法是什么.

There's really no way to know what the right syntax is without consulting the objects.inv.

 

scipy 大致与 numpy 一样难以理解. 由于为各种 scipy 引入了大量自定义域，事情变得更加复杂子包，例如:

scipy is roughly as inscrutable as numpy. Things are further complicated by the introduction of numerous custom domains for the various scipy subpackages, e.g.:

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

 

对于 matplotlib， 似乎您总是必须在引用中提供(相当冗长的)完全指定的对象名称，例如:

For matplotlib, it appears you always have to provide the (quite verbose) fully-specified object name in the reference, e.g.:

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

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

All of the matplotlib code objects seem to reside in the default py domain, however, which simplifies things somewhat.

 

对于其中任何一个，如果您在正确构建链接时遇到问题，我首先要考虑的是使用通用的 :obj: 角色，例如:

For any of these, if you're having trouble getting a link to construct properly, the first thing I fall back to is using the generic :obj: role, e.g.:

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

这将构造一个 intersphinx 链接，而不管定义特定对象的角色如何，尽管我认为您仍然必须正确指定任何相关的非默认域.如果引用不能与:obj:角色一起正常使用，则对象名称或某个域中的域存在错误.在两个地方检查错别字.

This will construct an intersphinx link regardless of the role in which a particular object was defined, though I think you still have to correctly specify any relevant non-default domain. If the reference doesn't work properly with an :obj: role, then there's an error in the object name or the domain somewhere. Check for typos in both places.

这篇关于指定指向 numpy、scipy 和 matplotlib 的 intersphinx 链接的目标的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！