Since this is no longer using automodule, SubplotParams, which was moved out of Figure on main (#26634) is still required in the figure module here, @jklymak @timhoffm do you have a preference for where that gets added?

• In its own subheading?
• Under SubplotLayout
• under discouraged or deprecated (which seems not quite right, though the location fits)
• something else?
• forgo backporting this change?

I suppose the other option would be to add the doc in gridspec, even though the implementation didn't change for this branch? feels slightly odd to do that, though

Sorry, a bit confused - moving SubplotParams didn't get in 3.8?

Sorry, a bit confused - moving SubplotParams didn't get in 3.8?

No. I just tagged it for 3.9 to be on the safe side (the fully qualified class name changes) and because I thought there is no hurry.

What a mess. This is surprisingly nasty. I'm afraid every solution to bring this backport into 3.8.1 is a nuissance.

Options:

1. "I suppose the other option would be to add the doc in gridspec, even though the implementation didn't change for this branch?"
   Pro: The doc is forward compatible.
   Con: SubplotParams is not part of gridspec in 3.8. -> We need to backport the above moving PR to 3.8.1
2. Put the doc back in figure docs somewhere.
   Pro: Documentation place matches still implementation place.
   Con: We have to remove it for 3.9 again, which we will forget. - Can we only do this in the 3.8.x branch or will that be merged back into master?
3. Do not backport this PR.
   Pro: Straight forward solution
   Pro: It's a real improvement and holding it back still half a year would be a pity.

My preference is exactly 1 > 2 > 3, assuming we are sure enough #26634 is safe for a bugfix release.

2. Put the doc back in figure docs somewhere.
   Pro: Documentation place matches still implementation place.
   Con: We have to remove it for 3.9 again, which we will forget. - Can we only do this in the 3.8.x branch or will that be merged back into master?

Where would it go?

Yes, the branch will be merged back up when a release is made. However, I don't think there's any worry about it being forgotten. I think there will be a conflict between the two branches due to the slightly different contents,. Additionally the failures here are for .SubplotParams.update (no module specified), meaning that docs should fail if we have it documented in two places, as Sphinx will warn about ambiguous references.

I've decided to forgo this change for the 3.8.1 release, in the interest of getting that tagged. We could still try to do it for 3.8.2 if we want, but I think it will be a manual backport including both the changes here and from #27110