@timhoffm and@anntzer before I go nuts with the docs for this, early feedback on the API would be welcome...

We should perhaps do a call to hash out the API decisions both for this and for#12679 once and for all...

Ok but this pr is completely agnostic of how the legend position is specified. If we later decide to do something with compass notation that doesn't change this PR at all.

I did not have the time to read through this completely and make my own thoughts.

Some quick observations though:

• fig.legend(loc='upper right', outside='upper') does not speak to me. This seems like a too clever way to put in additional degrees of freedom.
• Legend positioning is already a bit of a mess. I always struggle with thebbox_to_anchor option modifying the meaning ofloc. I feel it's getting worse with an addtional parameter.
• Which positions do we want to address. Are these essentially the A-L ones from the cheatsheet?
  
  Or even more, including the outer edges? The image makes clear that there are more outer positions than inner positions so that a simple additionaloutside bool cannot be enough. MATLAB folds this into the string. e.g. 'westoutside'. I'm wondering if that's a better choice.
• Semi-OT: Could Axes legend also be made to work "outside" with constrained_layout?

The cheatsheet way of doing things with bbox_to_anchor is basically what this seeks to avoid. Hopefully we can all agree that getting A, on the left side, by sayingloc="upper right", bbox_to_anchor=(-.1, .9) is not an acceptable API. Of course this won't break that, but I don't think we should be emulating it.

Here the proposal is:

A: loc="left", outside='upper'
B: loc="left", outside=True
C: loc="lower left", outside=True
D: loc="lower left", outside='lower'
E: loc="lower center", outside=True
F: loc="lower right", outside='lower'
G: loc="lower right", outside=True
H: loc="right", outside=True
I: loc="upper right", outside=True
J: loc="upper right", outside='upper'
K: loc="upper center", outside=True
L: loc="upper left", outside='upper'

Note that if the user specifiesbbox_to_anchor then theoutside kwarg is ignored.

I'm not wedded to this API, but actually feel (pretty strongly) that it is the simplest way forward, and doesn't lock us out of a different string-based API...

Yes, axes.legend can get outside placement, but lets save that for a separate PR.

... rebased

I'll advocate for this one as often-desired, and I'll also advocate for "lets keep it simple"

@jklymak Could the API be simplified by just having separate location specification for outside placement? so you either specify loc, or outside, but not both?

Also adding the two specifiers "top" and "bottom" then results in the following API:
A: outside='upper left'
B: outside="left"
C: outside="lower left"
D: outside="bottom left"
E: outside="bottom"
F: outside="bottom right"
G: outside="lower right"
H: outside="right"
I: outside="upper right"
J: outside="top right"
K: outside="top"
L: outside="top left"

As the illustration makes clear, in the outside case there is a degeneracy/ambiguity between the two sides of the corners that the current loc position names doesn't have to deal with. To me it seems reasonable that a clear resolution of this ambiguity is solved at the cost of introducing two new (relative) position specifiers.

I like the idea of separate kwargs for inside versus outside. For the outside naming, maybe specify row or column first, position within row or column second:
A: outside='left top'
B: outside="left middle"
C: outside="left bottom"
D: outside="bottom left"
E: outside="bottom middle"
F: outside="bottom right"
G: outside="right bottom"
H: outside="right middle"
I: outside="right top"
J: outside="top right"
K: outside="top middle"
L: outside="top left"

It's far from perfect, but I think this is a better match to the way I might describe a location around the periphery of the box, without consulting a diagram every time.

Another option would be to ditch the separate "left top" and "top left" and just use compass locations and names for everything. Inside or outside, there are just 4 corner locations, "NE", "SE", etc. Simple, concise, and unambiguous.
On second thought, I guess those diagonal locations are poor for legends, so the modified compass forms would be "NE top", "NE right", etc.

Probably most relevant demo is:https://output.circle-artifacts.com/output/job/0c5844ae-7ddf-4908-b96f-8bca79edd0af/artifacts/0/doc/build/html/tutorials/intermediate/legend_guide.html#figure-legends

New docs:

• https://output.circle-artifacts.com/output/job/c6a8b544-224a-4b58-8536-c5557fb07f7b/artifacts/0/doc/build/html/api/legend_api.html
• https://output.circle-artifacts.com/output/job/c6a8b544-224a-4b58-8536-c5557fb07f7b/artifacts/0/doc/build/html/api/figure_api.html
• https://output.circle-artifacts.com/output/job/c6a8b544-224a-4b58-8536-c5557fb07f7b/artifacts/0/doc/build/html/api/_as_gen/matplotlib.axes.Axes.legend.html#matplotlib.axes.Axes.legend

BTW, this is not particularly hard to re-milestone if it's slowing down the release. OTOH, I think it's substantively done, and oft-requested.

Easy enough to change to_outside_loc or something like that. For the main code itis basically a boolean. It only gets used as a string inside_constrained_layout.py.

Changedself._outside toself._outside_loc

Thanks for the reviews!

Just dropping in to share some ❤️ for this feature, just used it for the first time and it's so helpful!