如何用interphinx正确写入外部文档的交叉引用？ [英] How to properly write cross-references to external documentation with intersphinx?
问题描述
我使用的是狮身人面像（1.3.1 ）与Python（2.7.3），我的星座映射配置为：
{
'python':( 'https://docs.python.org/2.7'，无），
'numpy'：（'http://docs.scipy.org/doc/numpy/'，无），
'cv2'：（'http://docs.opencv.org/2.4/'，无），
'h5py'：（'http://docs.h5py.org/en/latest/'，无）
}
我没有麻烦编写一个交叉引用的numpy API与：class：`numpy.ndarray` 或：func：`numpy.array` numpy.ndarray 。
然而，使用h5py，生成链接的唯一方法是省略模块名称。例如，：class：`Group` （或：class：`h5py：Group` ）给我组，但：class：`h5py。 Group` 无法生成链接。
最后，我找不到一种编写OpenCV API的工作交叉引用的方法，这些似乎工作：
：func：`cv2.convertScaleAbs`
：func：`cv2：cv2.convertScaleAbs `
：func：`cv2：convertScaleAbs`
：func：`convertScaleAbs`
如何正确地将交叉引用写入外部API，或者配置interphinx，在numpy情况下生成链接？
我尝试了解一下 objects.inv 文件的内容，希望这次我检查了numpy和h5py而不是OpenCV的一个。
如何阅读会话空间库存文件
尽管事实上，我没有找到任何有用的阅读 object.inv 文件的内容，但实际上，这是一个简单的interphinx模块。
从sphinx.ext.intersphinx导入fetch_inventory
导入警告
uri ='http：// docs。 python.org/2.7/'
＃将库存读入一个dictionnary
inv = fetch_inventory（warnings，uri，uri +'objects.inv'）
这里我使用警告模块作为第一个参数，而不是应用程序实例，因为如果您获取在线uri，则只有 app.warn 函数用于发生故障时。如果您想要阅读本地的 objects.inv ，则需要一个真正的应用程序（或鸭式键盘）文件
文件结构（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：clas s domain：
{u'AttributeManager'：（u'h5py'，
u'2.5'，
u'http：//docs.h5py.org/en/latest/high/attr.html#AttributeManager'，
u'-'），
u'数据集'：（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交叉引用...
结论
我根据文件项目的内容以标准方式生成了 objects.inv ，这似乎并非如此。
因此，似乎编写交叉引用的正确方法是依赖于API，并且应该检查特定的库存对象来实际查看可用的。
I'm trying to add cross-references to external API into my documentation but I'm facing three different behaviors.
I am using sphinx(1.3.1) with Python(2.7.3) and my intersphinx mapping is configured as:
{
'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)
}
I have no trouble writing a cross-reference to numpy API with :class:`numpy.ndarray` or :func:`numpy.array` which gives me, as expected, something like numpy.ndarray.
However, with h5py, the only way I can have a link generated is if I omit the module name. For example, :class:`Group` (or :class:`h5py:Group`) gives me Group but :class:`h5py.Group` fails to generate a link.
Finally, I cannot find a way to write a working cross-reference to OpenCV API, none of these seems to work:
:func:`cv2.convertScaleAbs`
:func:`cv2:cv2.convertScaleAbs`
:func:`cv2:convertScaleAbs`
:func:`convertScaleAbs`
How to properly write cross-references to external API, or configure intersphinx, to have a generated link as in the numpy case?
I gave another try on trying to understand the content of an objects.inv file and hopefully this time I inspected numpy and h5py instead of only OpenCV's one.
How to read an intersphinx inventory file
Despite the fact that I couldn't find anything useful about reading the content of an object.inv file, it is actually very simple with the intersphinx module.
from sphinx.ext.intersphinx import fetch_inventory
import warnings
uri = 'http://docs.python.org/2.7/'
# Read inventory into a dictionnary
inv = fetch_inventory(warnings, uri, uri + 'objects.inv')
Here I use the warnings module as the first parameter instead of an app instance because if you fetch an online uri, only the app.warn function is used in case of failure. A real app (or a duck-typed one) will be needed if you want to read a local objects.inv file.
File structure (numpy)
After inspecting numpy's one, you can see that keys are domains:
[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']
You can see how you can write your cross-reference when you look at the content of a specific domain. For example, 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'-'),
...}
So here, :class:`numpy.DataSource` will work as expected.
h5py
In the case of h5py, the domains are:
[u'py:attribute', u'std:label', u'py:method', u'py:function', u'py:class']
and if you look at the py:class domain:
{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'-'),
...}
That's why I couldn't make it work as numpy references. So a good way to format them would be :class:`h5py:Dataset`.
OpenCV
OpenCV's inventory object seems malformed. Where I would expect to find domains there is actually 902 function signatures:
[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'
...]
and if we take the first one's value:
{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#$ -')}
I'm pretty sure it is then impossible to write OpenCV cross-references with this file...
Conclusion
I thought intersphinx generated the objects.inv based on the content of the documentation project in an standard way, which seems not to be the case.
As a result, it seems that the proper way to write cross-references is API dependent and one should inspect a specific inventory object to actually see what's available.
这篇关于如何用interphinx正确写入外部文档的交叉引用？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
