Gal*_*all 21 python documentation opencv python-sphinx autodoc
我正在尝试将外部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)
}
我可以毫不费力地编写numpy API的交叉引用,:class:`numpy.ndarray`或者: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情况下生成链接？
Gal*_*all 24
我试图了解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之后,您可以看到密钥是域:
[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的情况下,域名是:
[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的库存对象似乎格格不入.在我希望找到域名的地方,实际上有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交叉引用是不可能的......
我认为intersphinx objects.inv以标准方式生成基于文档项目内容的内容,但似乎并非如此.因此,似乎编写交叉引用的正确方法是依赖于API的,并且应该检查特定的库存对象以实际查看可用的内容.
lin*_*ish 21
除了@gall的详细解答之外,我发现它intersphinx也可以作为模块运行:
python -m sphinx.ext.intersphinx 'http://python-eve.org/objects.inv'
这输出格式正确的信息.供参考:https://github.com/sphinx-doc/sphinx/blob/master/sphinx/ext/intersphinx.py#L390
检查objects.inv文件的另一种方法是使用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:（我很乐意知道为什么）。