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

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

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

{
'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`

或

：func:`numpy.array`

编写对numpy API的交叉引用没有问题，正如预期的那样，这给了我类似的东西

但是，对于h5py，生成链接的唯一方法是省略模块名。例如，

：class:`Group`

（或

：class:`h5py:Group`

）为我提供了链接，但

：class:`h5py.Group`

无法生成链接

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

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

---

如何正确地编写对外部API的交叉引用，或配置intersphinx，以生成numpy案例中的链接？

我尝试了另一次尝试，试图理解

objects.inv

文件的内容，希望这次我检查了numpy和h5py，而不仅仅是OpenCV的一个

如何读取intersphinx清单文件 尽管我找不到任何关于读取

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的one后，您可以看到密钥是域：

[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'：'，
u'AdjusterAdapter:：创建（常量），
u'AdjusterAdapter:：good（）'，
u'AdjusterAdapter:：TooNow（int'，
u'AdjusterAdapter:：太多（int'，
u'算法：：创建（常量'，
u'算法：：getList（向量&'，
u'Algorithm:：name（）'，
u'算法：：读取（常量'，
u'算法：：集合（常量'
...]

如果我们取第一个的值：

{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#$ -')}

{u'Ptr'：（u'OpenCV'，
u'2.4'，
u'http://docs.opencv.org/2.4/detectorType)',
u'ocv:function 1 modules/feature2d/doc/common_interfaces_of_feature_detectors.html#$-'）}

我很确定，用这个文件写OpenCV交叉引用是不可能的

结论 我认为intersphinx以标准方式基于文档项目的内容生成了

objects.inv

，但事实似乎并非如此。

---

因此，编写交叉引用的正确方法似乎取决于API，人们应该检查特定的库存对象以实际查看可用的内容。

除了@gall提供的详细答案外，我还发现

intersphinx

还可以作为模块运行：

python -m sphinx.ext.intersphinx 'http://python-eve.org/objects.inv'

---

这将输出格式良好的信息。供参考：

接受的答案在新版本（1.5.x）中不再有效

如何使用OpenCV 2.4（cv2）intersphinx 受@Gall答案的启发，我想比较OpenCV和numpy清单文件的内容。我无法从ipython获取

sphinx.ext.intersphinx.fetch_inventory

，但以下方法确实有效：

curl http://docs.opencv.org/2.4/objects.inv | tail -n +5 | zlib-flate -uncompress > cv2.inv
curl https://docs.scipy.org/doc/numpy/objects.inv | tail -n +5 | zlib-flate -uncompress > numpy.inv

numpy.inv有如下行：

numpy.ndarray py:class 1 reference/generated/numpy.ndarray.html#$ -

cv2.imread ocv:pyfunction 1 modules/highgui/doc/reading_and_writing_images_and_video.html#$ -

而cv2.inv有如下行：

numpy.ndarray py:class 1 reference/generated/numpy.ndarray.html#$ -

cv2.imread ocv:pyfunction 1 modules/highgui/doc/reading_and_writing_images_and_video.html#$ -

因此，您可能会使用

：ocv:pyfunction:`cv2.imread`

链接到OpenCV文档，而不是

：py:function:`cv2.imread`

。不过Sphinx不喜欢它：

警告：未知的解释文本角色“ocv:pyfunction”

一点Google显示OpenCV项目有自己的“OCV”狮身人面像域：大概是因为他们需要同时记录C、C++和Python API。 要使用它，请在Sphinx

conf.py

旁边保存

ocv.py

，然后修改

conf.py

：

sys.path.insert(0, os.path.abspath('.'))
import ocv
extensions = [
    'ocv',
]
intersphinx_mapping = {
    'cv2': ('http://docs.opencv.org/2.4/', None),
}

在rst文件中，您需要说

：ocv:pyfunc:`cv2.imread`

（而不是

：ocv:pyfunction:

）

---

狮身人面像打印一些警告（<代码>不可解析的C++定义：U'CV2.imim''/COD>），但是生成的HTML文档实际上可以用链接来连接。您可以编辑<代码> OCV.Py < /C> >并删除打印警告的行。< /P> < P> >检查<代码>对象。 您可以搜索本地甚至远程库存文件（使用模糊匹配）。例如，使用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:

（我很高兴知道原因）。

我是个顽固的傻瓜，我使用了

2to3

和来恢复，因此它将与Python 3.5上的Sphinx 2.3一起工作

固定版本如下：

…我所做的快速版本是：

运行

2to3-w ocv.py和&rm ocv.py.bak

在运行Sphinx和将函数重命名为其在图表中的替换项之间来回循环。我相信这是我在这一步所做的唯一更改：

指令

现在必须从

docutils.parsers.rst

将对

l_（…）

的调用替换为对

l_（…）

的调用，并删除导入

将对

env.warn

的调用替换为对

log.warn

的调用，其中

log=sphinx.util.logging.getLogger（\uu name\uuu）

然后，您只需将其与intersphinx定义配对，就可以得到一些新的东西，这些新东西足以与大多数用例相关：

'cv2': ('https://docs.opencv.org/3.0-last-rst/', None)

---

为了方便起见，我对intersphinx交叉引用的别名做了一个小小的扩展