This is nice but same concern as previous one of these: most folks consume the api docs in IDEs and may be frustrated they cannot reach this. It'd be nice to work on a solution that allowed both the image and a link.

Same answer: Link sounds nice but in a text-based renderer a usable realization is non-trivial. How should the link look like? Where should it point to? How would it be used?

The plots I add are supplementary illustrations. You can get all information from the text. It think we have to accept that some interfaces to the docstrings are just less capable and cannost show illustrations / have links. - We also live with the fact that code links like .Axes.set_xlim do not work in plain text.

It would take a new directive I suppose, but something like

.. example-plot:: https://matplotlib.org/stable/example_plots/example_subplots_adjust.png

which then either just display that in the rendered docs, or generated it from example_plots/example_subplots_adjust.py would be nicer. Of course the link being clickable would depend on the IDE.

.. image:: https://matplotlib.org/stable/example_plots/example_subplots_adjust.png

would be fine too if sphinx allowed the image directive to use an html. That has a bootstrapping problem in that the example plot would need to be on stable, whereas a new directive that created the file and put in the right spot would be better (the absolute path would be ignored in rendering).

I would support such a directive. As you said, there are a number of aspects to work out. Related: It may also be an idea to have a link in every API doc something like: "Online version: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.margins.html" at the bottom. With that one gets access not only to the image but cross-references, related examples etc.

But all of this is off-topic. In this PR I'm just adding content, that is for now helpful in the HTML docs. Whether one can additionally find better representations in the raw docstring is orthogonal. Also, I believe it's helpful to start with the content. If we only need/have such images in one or two places, the work for a extension may not be justifed. But having already several plots can be a motivation for the extension.

Feel free to self merge when build done