如何使用intersphinx正确编写对外部文档的交叉引用？

Question

我试图在我的文档中添加对外部API的交叉引用，但是我面临三种不同的行为。

我正在将sphinx（1.3.1）与Python（2.7.3）一起使用，并且我的sphinx映射配置为：

{
'python': ('https://docs.python.org/2.7', None),
'numpy': ('http://docs.scipy.org/doc/numpy/', None),
'cv2' : ('http://docs.opencv.org/2.4/', None),
'h5py' : ('http://docs.h5py.org/en/latest/', None)
}

我毫不费力地用:class:numpy.ndarray或编写了对numpy API的交叉引用，`:func:`numpy.array这使我得到了像numpy.ndarray这样的东西。

但是，对于h5py，唯一可以生成链接的方法是忽略模块名称。例如，:class:Group（或`:class:`h5py:Group）给我Group，但:class:h5py.Group``无法生成链接。

最后，我找不到一种方法来编写对OpenCV API的有效交叉引用，但这些似乎都不起作用：

:func:`cv2.convertScaleAbs`
:func:`cv2:cv2.convertScaleAbs`
:func:`cv2:convertScaleAbs`
:func:`convertScaleAbs`

如何正确地编写对外部API的交叉引用，或配置intersphinx，使其具有生成的链接（如numpy情况）？

Answer 1

我再次尝试理解objects.inv文件的内容，希望这次我检查了numpy和h5py而不是仅检查了OpenCV的文件。

如何读取一个狮身人面像清单文件

尽管我找不到任何有关读取object.inv文件内容的有用信息，但使用intersphinx模块实际上非常简单。

from sphinx.ext import intersphinx
import warnings


def fetch_inventory(uri):
    """Read a Sphinx inventory file into a dictionary."""
    class MockConfig(object):
        intersphinx_timeout = None  # type: int
        tls_verify = False

    class MockApp(object):
        srcdir = ''
        config = MockConfig()

        def warn(self, msg):
            warnings.warn(msg)

    return intersphinx.fetch_inventory(MockApp(), '', uri)


uri = 'http://docs.python.org/2.7/objects.inv'

# Read inventory into a dictionary
inv = fetch_inventory(uri)
# Or just print it
intersphinx.debug(['', uri])

文件结构（numpy）

检查numpy的密钥后，您可以看到密钥是域：

[u'np-c:function',
 u'std:label',
 u'c:member',
 u'np:classmethod',
 u'np:data',
 u'py:class',
 u'np-c:member',
 u'c:var',
 u'np:class',
 u'np:function',
 u'py:module',
 u'np-c:macro',
 u'np:exception',
 u'py:method',
 u'np:method',
 u'np-c:var',
 u'py:exception',
 u'np:staticmethod',
 u'py:staticmethod',
 u'c:type',
 u'np-c:type',
 u'c:macro',
 u'c:function',
 u'np:module',
 u'py:data',
 u'np:attribute',
 u'std:term',
 u'py:function',
 u'py:classmethod',
 u'py:attribute']

当您查看特定域的内容时，可以看到如何编写交叉引用。例如py:class：

{u'numpy.DataSource': (u'NumPy',
  u'1.9',
  u'http://docs.scipy.org/doc/numpy/reference/generated/numpy.DataSource.html#numpy.DataSource',
  u'-'),
 u'numpy.MachAr': (u'NumPy',
  u'1.9',
  u'http://docs.scipy.org/doc/numpy/reference/generated/numpy.MachAr.html#numpy.MachAr',
  u'-'),
 u'numpy.broadcast': (u'NumPy',
  u'1.9',
  u'http://docs.scipy.org/doc/numpy/reference/generated/numpy.broadcast.html#numpy.broadcast',
  u'-'),
  ...}

所以在这里，:class:numpy.DataSource``将按预期工作。

h5py

对于h5py，域为：

[u'py:attribute', u'std:label', u'py:method', u'py:function', u'py:class']

并且如果您查看py:class域：

{u'AttributeManager': (u'h5py',
  u'2.5',
  u'http://docs.h5py.org/en/latest/high/attr.html#AttributeManager',
  u'-'),
 u'Dataset': (u'h5py',
  u'2.5',
  u'http://docs.h5py.org/en/latest/high/dataset.html#Dataset',
  u'-'),
 u'ExternalLink': (u'h5py',
  u'2.5',
  u'http://docs.h5py.org/en/latest/high/group.html#ExternalLink',
  u'-'),
 ...}

这就是为什么我无法使其作为numpy引用工作的原因。所以格式化它们的好方法是:class:h5py:Dataset``。

OpenCV的

OpenCV的清单对象似乎格式错误。我希望找到域的地方实际上有902个函数签名：

[u':',
 u'AdjusterAdapter::create(const',
 u'AdjusterAdapter::good()',
 u'AdjusterAdapter::tooFew(int',
 u'AdjusterAdapter::tooMany(int',
 u'Algorithm::create(const',
 u'Algorithm::getList(vector<string>&',
 u'Algorithm::name()',
 u'Algorithm::read(const',
 u'Algorithm::set(const'
 ...]

如果我们采用第一个值：

{u'Ptr<AdjusterAdapter>': (u'OpenCV',
  u'2.4',
  u'http://docs.opencv.org/2.4/detectorType)',
  u'ocv:function 1 modules/features2d/doc/common_interfaces_of_feature_detectors.html#$ -')}

我很确定那时不可能用此文件编写OpenCV交叉引用…

结论

我以为intersphinxobjects.inv以 标准
方式基于文档项目的内容生成了，似乎并非如此。结果，似乎写交叉引用的正确方法依赖于API，因此应该检查特定的清单对象以实际查看可用的对象。