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

Question

Following the documentation for setting up Sphinx documentation links between packages, I have added

intersphinx_mapping = {\'python\': (\'http://docs.python.or         


        

Answer 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.