Consider adding the possibility for linking between examples. Is this technically only a ".. seealso::" directive?

I think ideally there would be a minigallery defined by the example. Though im not sure sphinx-gallery supports that.

@timhoffm does this issue needs work?

Yes it does.

There are multiple things to do here:

The trivial thing would be to just write down what we're currently doing. See, e.g. https://matplotlib.org/devdocs/gallery/lines_bars_and_markers/fill.html#references.

However this is more like a hack with several drawbacks, which is why I'm a bit hesitant to document it as the recommended solution

• You need to put import matplotlib in
• You get the Out[] line.
• You have to mention pyplot as well as Axes to get references in both docs.

Also, I had the impression that this way of writing code and let sphinx gallery discover it does not always work, but I cannot point at an example right now.

The good solution would be to write a sphinx directive

.. gallery-reference::
   matplotlib.axes.Axes.fill
   matplotlib.pyplot.fill
   matplotlib.axes.Axes.axis
   matplotlib.pyplot.axis

That'd possibly be need to be done upstream in sphinx-gallery.

Proposal: Switch to

###############################################################################
#
# .. admonition:: References
#
#    The use of the following functions, methods, classes and modules is shown
#    in this example:
#
#    - `matplotlib.axes.Axes.fill` / `matplotlib.pyplot.fill`
#    - `matplotlib.axes.Axes.axis` / `matplotlib.pyplot.axis`

Which results in

This works without defining any new directives.

For comparison: Current look