The part of the sphinx docs that describe this feature are here:

https://sphinx-gallery.readthedocs.io/en/latest/advanced_configuration.html#adding-references-to-examples

The part that configures this is the 'doc_module' and 'backreferences_dir' within the sphinx_gallery_conf:

There is an automated generation, as described in the next chapter,

https://sphinx-gallery.readthedocs.io/en/latest/advanced_configuration.html#auto-documenting-your-api-with-links-to-examples

Still trying to understand it.

Right, and the "*.example" files are being generated, but they aren't being populated.

Possibly (probably) because most examples don't import matplotlib.axes.Axes as maxes, but rather import pyplot and get an axes object from fig, ax = plt.subplots() or the like.

Right. If you look at the examples, those functions which are correctly linked from the examples to the docs are orange in the code and can be clicked,

Hence plt.contourf will have a gallery below it,

while Axes.contour doesn't, because those methods are not recognized,

Oh great, so pyplot gets more love than the OO docs... 😢

Not sure what to do about it, except see if sphinx could add a check for a convention like ax.Boo maps to axes.Axes.Boo...

And then.. what about ax2, ax3 and ax_array[0]?
The problem is also that the galleries are incomplete. Having an example which uses a pyplot function would get linked, one with an OO example would not. This is almost worse than having no gallery as users would not try to search for any further example if none of those provided below the function shows what they want to do.

On the other hand it is probably good not to have every single function linked, e.g. set_xlabel would then just link to every example of the gallery. Not sure. Doesn't seem like a problem with an easy solution.

So I guess for most methods this should just be done manually...

Maybe one can turn this around? Somehow tag the gallery examples with the API functions they are prominently using. Then backref the examples from the api functions.

Essentially like gallery does it, except that the connections are not automatically created but are defined by us. Probably one would have to hack into the gallery.backreferences code. Such manual backreferences would generally be a good feature and should be addressed upstream if possible.

pyplot functions and related Axes methods should have the same set of examples.

That's in principle a good idea. Now it seems that sphinx-gallery simply renders everything in those files as comments are just converted to text. So it might be hard to actually do this kind of tagging.

On the other hand this brings me to the idea, could it be possible to just mention the base function somewhere? This should trigger the linking. For example, suppose at the bottom of the example, there is a code sample like

#############################
# This example makes use of:

matplotlib.axes.Axes.contourf
matplotlib.pyplot.contourf

Would this be enough for it be included in both galleries?

The comments in those files are just rest text so can include all the rst directives we like. But there is no machinery right now to do the reference in this direction that I know of. Seems like a great feature request for Sphinx-gallery.

Not sure what to do about it, except see if sphinx could add a check for a convention like ax.Boo maps to axes.Axes.Boo...

As discussed above, a global setting would not work. However, if one could configure this within the example, that would be great and even add links to the code.

Seems like an alternative great feature request for Sphinx-gallery. 😄

I tried the above suggestion in this PR. It would look like this, see here for live preview:

This will ensure that the documentation is properly linked and indeed if you then go to the axes.Axes.imshow documentation you see there being the linked example at the bottom.

One drawback: It does not seem to work with functions which do not have their own doc page. In this case, although matplotlib.figure.Figure.colorbar is mentionned, the example does not appear in the examples list of matplotlib.figure.Figure; but it does appear in the one from matplotlib.pyplot.colorbar because that has its own doc page.

👍 👍 on this as a great way to go. Now we just have to populate a critical mass of examples... At the very least we can ask new PRs to do this.

As an aside, I think there should be a matplotlib.axes.Axes.colorbar method. I'd say 99% of the colorbars I create are attached to an axes.

The only disadvantage to that method is we need to have import matplotlib somewhere in the example...

This is a good workaround for now. In the long run, I'd still want a sphinx-gallery feature to be able to define linking of arbitrary code pattens to documentation (and reverse).

This is not so much about sphinx-gallery. I don't think it can do anything here. What one might expect from sphinx-gallery is the option to hide this attached Reference section but still use it somehow. Even if possible, this would however still involve a manual procedure of adding the functions/methods/classes to each example individually.

In order to produce an automatic linkage, one would need to look at
sphinx.ext.autodoc and sphinx.ext.autosummary. Those (or only one of them?) are responsible for parsing the code and select the functions to link.
The problem is clearly that as it is now, the code itself is parsed in text form. If there is a module mymodule imported and you write mymodule.function() somewhere, it is rather easy to assign a link to it.
If however you have x = mymodule.function() and then want x.get_whatever() being linked to SomeClass.get_whatever, the parser needs to know that x is actually of type SomeClass. This is not possible from parsing the document, but you would actually need to run the code and perform typechecking. Especially for python, which is not very stringent with types, this is in general a hard problem. I have no idea if there are solutions to this available for use with sphinx, but the above is why I guess that there aren't.

It this solution also supplies links to the API doc in the example. I wouldn’t want to hide the References.

@ImportanceOfBeingErnest IMHO this is exactly about sphinx. I would want something like:

###########################################################
# .. type-hint::
#    ax: matplotlib.axes.Axes
#    fig: matplotlib.figure.Figure
fig, ax = plt.subplots()
ax.plot(t, s)
fig.savefig("test.png")

This should link ax.plot in the same way as plt.subplots.

Of course, this is manual since in general you cannot know what type a variable is unless you run the code. Still, it would allow linking of methods in the same way that's already available for functions.

Correct. To me it looks like this linkage is done by sphinx.ext.autodoc or
sphinx.ext.autosummary (or both?), so those are the modules to look at or for which to find an alternative. sphinx-gallery seems to just use whatever is given to it via those modules' output.

As also discussed in #11019 and #10148, the idea is now to create a reference section below examples to include the modules, functions, methods and classes that can serve as backreferences.

Here is a table of the current status.

[*] Might not be needed, as mplot3d section has examples inside the docs

Please feel invited to contribute.

(Maybe this can also the new-contributor-friendly label?)

It seems sphinx-gallery has a PR in for this. Not merged yet, as far as I can see:

sphinx-gallery/sphinx-gallery#347

As far as I can see, that PR would allow to put a reference like :meth:~axes.Axes.plot somewhere in the text part of an example and hence have the example added to that method's example section.

This is somehow the same as mentionning the actual method explicitely as code, like it's beeing done in the work here.

So instead of

#############################
# This example makes use of:

matplotlib.axes.Axes.contourf
matplotlib.pyplot.contourf

You would then be able to write

#############################
# This example makes use of:
# * :meth:`matplotlib.axes.Axes.contourf`
# * :meth:`matplotlib.pyplot.contourf`

which is somehow the same manual work that needs to be done.

I did btw. not continue to spend much effort into this because @anntzer mentionned at some point that he might have a better idea to do some automatic parsing. Not sure what the status of that is.

Agreed that the manual work is the same, but I think its less strange to have this list than a code block. And flake8 doesn't like having the import at the bottom of the page.

Better parsing is coming, but I'm also starting a new job so that project is a bit on the back burner for now... (sorry, didn't keep the schedule :) probably won't have the time to work seriously on it before this fall)

I think we can close this as being acted on...