Okay @jklymak thanks for your review, I have responded and fixed everything. The only concern I have is the comment about whether or not the list of subfigures should be entirely cleared in the parent when the parent calls clear. As I mentioned, I am concerned about any callbacks when a GUI widget is tracking an axis in the subfigures.

I would expect fig.clear to remove all children. If there are callbacks that I expected to stay alive, I shouldn't clear the whole figure?

Sounds fine to me @jklymak. The latest commit follows this convention.

/home/circleci/project/doc/api/next_api_changes/behavior/22135-JSS3.rst:2: WARNING: Title underline too short. ;-)

Wow. Fixed.

@jklymak what tool checks for RST style?

Our docs fail to build if there are warnings.

@stanleyjs Would you mind also squashing this to one commit (or we can do that on merge)?

doc build is still unhappy...

Hi @stanleyjs unfortunately this needs a rebase whereby you will need to resolve the conflicts in figure.py. When you have done so and fixed the doc mistake, please ping me and I'll try an merge expeditiously. If you need assistance with a rebase, feel free to ask here or on gitter. Thanks!

Sorry, did not mean to let this stagnate. I'll look into this ASAP

@jklymak It did not appear to need an actual rebase, i was able to just resolve the merge conflicts. We'll see if it passes CI

@stanleyjs We prefer to rebase rather than merge the main branch into the feature branches.

@tacaswell Very well. I definitely don't know how to rebase, but I guess there's a first time for everything

@tacaswell @jklymak Can you point me in a direction on how to optimally use rebase? Or can you rebase it yourself? I just rebased it once, then the branch was 200 commits behind, so I merged it and tried to rebase the merge and the previous rebase into a single commit again and got stuck manually merging 200+ commits. I aborted after awhile, as I could not tell what commit was important without manually verifying each change in main. I have no idea what to do.

Using rebasing definitly takes a few times through to have it make sense! We have some documentation on rebasing at https://matplotlib.org/stable/devel/gitwash/development_workflow.html#rebasing-on-trunk and the best thing I have ever read about git is https://tom.preston-werner.com/2009/05/19/the-git-parable.html

When git suggests you merge the remote branch into yours when the push fails, it is giving you conservative but very bad advice! At that point the correct path is git push --force-with-lease remote branch_name.

The steps I did here:

• went back to the commit before you merged master by clicking through the GH ui
• eventually I got to https://github.com/tacaswell/matplotlib/tree/6e4b1d9c45c413691a84edf04227cad039c78e29 which let me use the GH ui to create a branch on github at that commit (which I called "restore")
• I then checked out that branch locally
• I rebased that branch onto origin/master
• I had to manually resolve conflicts on 3 commits (dace9f4, 9dfcfd5, 1d5ba46). The first two were real conflicts that I think I resolved correctly, the third was whitespace. At each broken step git left me with the merge confilct markers. I use emacs + magit for this, but most IDEs have some sort of helper tool for dealing with this.
• I checked out 47c4a23 and pushed that to my fork as subfigure-clear as a backup!
• I force-pushed my rebased branch to your branch (I can do this because of the "let maintainers push to this branch" box which it ticked in your UI)

Hopefully these notes are more helpful than confusing!

It might still be worth using git rebase -i to squash this all down to one commit any way.

I'm not quite sure what happened here but somehow you had picked up changes on many many files. The diff from the current branch to cc71237 is:

diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py
index 7ef783265d..57ea70597f 100644
--- a/lib/matplotlib/figure.py
+++ b/lib/matplotlib/figure.py
@@ -922,17 +922,16 @@ default: %(va)s
         self.suppressComposite = None
         self.callbacks = cbook.CallbackRegistry()
 
+        # first clear the axes in any subfigures
         for subfig in self.subfigs:
-            # first clear the axes in any subfigures
             subfig.clf(keep_observers=keep_observers)
+        self.subfigs = []
 
         for ax in tuple(self.axes):  # Iterate over the copy.
             ax.cla()
             self.delaxes(ax)  # Remove ax from self._axstack.
-
         self._axstack = _AxesStack()
         self.artists = []
-        self.subfigs = []
         self.lines = []
         self.patches = []
         self.texts = []
@@ -2166,6 +2165,7 @@ class Figure(FigureBase):
             naxes=len(self.axes),
         )
 
+    @_api.make_keyword_only("3.6", "facecolor")
     def __init__(self,
                  figsize=None,
                  dpi=None,
@@ -2356,7 +2356,7 @@ class Figure(FigureBase):
         # figure...
         for ax in self.axes:
             if hasattr(ax, '_colorbar'):
-                # colorbars list themselvs as a colorbar.
+                # colorbars list themselves as a colorbar.
                 return False
         return True
 
@@ -2850,10 +2850,6 @@ class Figure(FigureBase):
         if toolbar is not None:
             toolbar.update()
 
-    def clear(self, keep_observers=False):
-        """Clear the figure -- synonym for `clf`."""
-        self.clf(keep_observers=keep_observers)
-        
     @_finalize_rasterization
     @allow_rasterization
     def draw(self, renderer):

I meant to remove the subclass clear (the one from the parent class will do and correctly get the right clf) and I moved the resetting of self.subfigs up a bit to make it easier to read (which is subjective).

I squashed down to one commit so we pass the PR cleanliness check (not add / remove a file).

One naming issue here. clf means "clear last figure",

I have always read this as "CLear Figure" / "CLear Axes", but that aside, Figures have clf and if we want SubFigures to be drop-ins for Figures then SubFigures also need clf, but I'm on board with flipping the usage and alias direction to prefer clear.

Oh, hmmm, well I looked up Matlab's docs and they just say "clear figure", so maybe you are right, and indeed clf takes a figure argument in Matlab, so I guess I am incorrect.

Owee, I'm MrMeeseeks, Look at me.

There seem to be a conflict, please backport manually. Here are approximate instructions:

1. Checkout backport branch and update it.

git checkout v3.5.x
git pull

2. Cherry pick the first parent branch of the this PR on top of the older branch:

git cherry-pick -x -m1 a395083238625500dd3fa879e4976617d5353342

3. You will likely have some merge/cherry-pick conflict here, fix them and commit:

git commit -am 'Backport PR #22138: Fix clearing subfigures'

4. Push to a named branch:

git push YOURFORK v3.5.x:auto-backport-of-pr-22138-on-v3.5.x

5. Create a PR against branch v3.5.x, I would have named this PR:

"Backport PR #22138 on branch v3.5.x (Fix clearing subfigures)"

And apply the correct labels and milestones.

Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon!

Remember to remove the Still Needs Manual Backport label once the PR gets merged.

If these instructions are inaccurate, feel free to suggest an improvement.

I had a commit (not pushed) to fix the naming. I'll make a new PR.