Specifying targets for intersphinx links to numpy, scipy, and matplotlib

Solution 1:

Where can I find instructions on how to specify targets for :ref:s and :term:s in numpy, scipy, and matplotlib?

I have a Gist with a handful of intersphinx mappings, which now includes all of numpy, scipy and matplotlib. You should be able to use these entries directly in intersphinx_mapping, within your conf.py. If anyone has suggestions for further entries to be added to this list, please feel free to post requests into the comments of the Gist.

For all of these packages, per fgoudra's answer I highly recommend using sphobjinv to search within the objects.inv file for each library. (Full disclosure: I am the author of sphobjinv.) The suggest mode of the CLI interface is specifically designed to provide the information needed to compose intersphinx cross-references.

numpy is complicated. Sometimes you need a fully-qualified name, e.g.:

:func:`numpy.cross`

Other times (for C functions, for example) you can just reference the function's base name BUT you have to explicitly indicate the domain, e.g.:

:c:func:`PyArray_InnerProduct`

Yet other times you may have to reference the custom np domain, e.g.:

:np:func:`numpy.ma.append`

There's really no way to know what the right syntax is without consulting the objects.inv.

scipy is roughly as inscrutable as numpy. Things are further complicated by the introduction of numerous custom domains for the various scipy subpackages, e.g.:

:scipy-optimize:func:`scipy.integrate.newton_cotes`

For matplotlib, it appears you always have to provide the (quite verbose) fully-specified object name in the reference, e.g.:

:meth:`matplotlib.axes.Axes.plot`

All of the matplotlib code objects seem to reside in the default py domain, however, which simplifies things somewhat.

For any of these, if you're having trouble getting a link to construct properly, the first thing I fall back to is using the generic :obj: role, e.g.:

:obj:`matplotlib.axes.Axes.plot`

This will construct an intersphinx link regardless of the role in which a particular object was defined, though I think you still have to correctly specify any relevant non-default domain. If the reference doesn't work properly with an :obj: role, then there's an error in the object name or the domain somewhere. Check for typos in both places.

Solution 2:

In case this is still an issue.. you need to leave out the slash at the end of the URL:

intersphinx_mapping = {'python': ('http://docs.python.org/2', None),
                       'numpy': ('http://docs.scipy.org/doc/numpy', None),
                       'scipy': ('http://docs.scipy.org/doc/scipy/reference', None),
                       'matplotlib': ('http://matplotlib.org/stable', None)}

Solution 3:

It is possible to manually specify which inventory to look. For example, if intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None) does not work, you can always download the inventory and manually append it to the mapping (e.g. download from http://sphinx-doc.org/objects.inv, save the binary file in your docs and append the path to it in the mapping; this will give something like:

intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', ('objects.inv', ), )

To verify if a reference exists within the inventory, you can explore the binary with the sphobjinv python package and check where is the reference you want.

This may not be a solution to your problem but can help to debug some things.

Solution 4:

An additional way to know how to do cross reference is with the sphobjinv module.

You can search local or even remote inventory files (with fuzzy matching). For instance with 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`

Note that you may need to use :py:func: and not :py:function: (I'd be happy to know why).