python - How to properly write cross-references to external documentation with intersphinx? -

i'm trying add cross-references external api documentation i'm facing 3 different behaviors.

i using sphinx(1.3.1) python(2.7.3) , intersphinx mapping 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 cross-reference numpy api :class:`numpy.ndarray` or :func:`numpy.array` gives me, expected, numpy.ndarray.

however, h5py, way can have link generated if omit module name. example, :class:`group` (or :class:`h5py:group`) gives me group :class:`h5py.group` fails generate link.

finally, cannot find way write working cross-reference opencv api, none of these seems work:

:func:`cv2.convertscaleabs` :func:`cv2:cv2.convertscaleabs` :func:`cv2:convertscaleabs` :func:`convertscaleabs` 

how write cross-references external api, or configure intersphinx, have generated link in numpy case?

i gave try on trying understand content of objects.inv file , time inspected numpy , h5py instead of opencv's one.

how read intersphinx inventory file

despite fact couldn't find useful reading content of object.inv file, simple intersphinx module.

from sphinx.ext import intersphinx import warnings   def fetch_inventory(uri):     """read sphinx inventory file 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 dictionary inv = fetch_inventory(uri) # or print intersphinx.debug(['', uri]) 

file structure (numpy)

after inspecting numpy's one, can see keys 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 can write cross-reference when @ content of specific domain. 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` work expected.

h5py

in case of h5py, domains are:

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

and if @ 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 couldn't make work numpy references. way format them :class:`h5py:dataset`.

opencv

opencv's inventory object seems malformed. expect find domains there 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 take 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 impossible write opencv cross-references file...

conclusion

i thought intersphinx generated objects.inv based on content of documentation project in standard way, seems not case. result, seems proper way write cross-references api dependent , 1 should inspect specific inventory object see what's available.