Specifying targets for intersphinx links to numpy, scipy, and matplotlib
matplotlib, numpy, python, python-sphinx, scipy
Solution
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.
Problem
Following the documentation for setting up Sphinx documentation links between packages, I have added ``` 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.sourceforge.net/', None)} ``` to my `conf.py`, but can't seem to get links to any project other than Python itself to work. For example ``` :term:`svg graphics <matplotlib:svg>` ``` just takes me to the index page, without adding the expected `#term-svg` anchor, and I can't even locate the glossary for `scipy` or figure out how to determine what `:ref:`s or `:term:`s are supported by a package. Where can I find instructions on how to specify targets for `:ref:`s and `:term:`s in `numpy`, `scipy`, and `matplotlib`? For that matter, how do I link to Sphinx itself? Adding ``` intersphinx_mapping['sphinx'] = ('http://sphinx-doc.org/', None) ``` and ``` :ref:`Intersphinx <intersphinx>` ``` doesn't work.