This seems like a complicated example for the ApI docs? Would we not prefer just a link-out here to a standalone example?

This is not an example in the sense that the code is relevant. The rendered picture is. The code does not show up in the rendered docs:

https://output.circle-artifacts.com/output/job/00757267-8a4a-46fe-96a5-f087064abf30/artifacts/0/doc/build/html/api/_as_gen/matplotlib.axes.Axes.margins.html#matplotlib.axes.Axes.margins

we could alternatively embed a static image, but it's slightly simpler to adapt/maintain from code, and it's and "added feature" that an interested user can get the source via link. If you're concerned about raw docs, we could put the code into a separate file and

.. plot:: margins_illustration.py

Love the idea (and we already do some of this as a note in I think arrow to explain the angles), a little concerned that the arrows overlayed with the data here are hard to read:

Can this be stripped down to like a 3 by 4? and possibly instead of arrows, gray out or hatch the margin region like we do to explain the padding for figures?

New version:

and plot code separated to a file not not spam the raw docs too much.

I think that's way clearer as an explaination!

What about putting it in the gallery with a purpose: reference tag?

That way it's available for quick lookup for folks browsing the gallery and who may want the code, but also the tag indicates that this isn't intended as teaching code?

This is probably fine, though a link would work for rendered and raw docs. However the docs are not building on this pr

Links sound better than they are for raw docs. A link would look like :doc:/gallery/some_subgallery/margins. You cannot do anything useful with it from an interpreter. You have to go to the browser and find out how the link translates to an URL. I claim it's then simpler to go to the browser and open the margins() docs.

Another issue with putting this into the gallery as is, is that the plot is specifically designed for the visual result, it's not an instructive code example for margins.

Generally, I believe, there's a place for "plots embedded into the docstrings". Visualizations help. Naturally, we can only do them in HTML, not in raw docs). Putting the plot code into separate files helps to keep the raw docstings readable. Note that we don't have to go with separate files in .rst docs. They are not read in raw by users, so inline .. plot:: code is fine there.

This PR specifically, makes margins() more understandable by itself. I see it as reasonable incremental improvement for that limited scope. A more complete "explanation doc" on limit handling would be useful. This is on of the topics tracked in #20984.

I really need to proofread what I write and am very sorry for the confusion! I don't know how the don't got in there - I meant to say that I really like the folder for collecting these kinds of images cause I agree we need more of em. 🤦‍♀️

I just didn't merge in case you liked the gallery idea.

.