Just saw the failing test, which compares if the parameter sections are identical for axes.legend() and Legend().

I assume the intent is to keep the long parameter lists at sync. However since the signatures are actually different, this does not work easily. Either one has to break with the documenting rules and exclude parent, handles and labels from the parameter sections (probably why the docstring was in the peculiar state before I changed it), or one has to refine the test.

How should I proceed?

Without looking too closely, can you keep "Parameters" as the arguments that change, and "Other Paramters" as the parameters that are shared and move the test to look at the "Other Parameters" section?

The problem before was that the very very very long list of kwargs was not consistent between the legend docstrings. I fixed that, and then introduced the test (#9324). If it had been up to me, we'd have used a doc interp, but the consensus seemed to be that we don't like doc interps. I'm not particularly happy w/ the existing solution, so other creative ideas more than welcome. I'm not going to be terribly upset if we get rid of the test for consistency, but there should be a way to keep the kwarg documentation consistent between the three legends. See also #9414.

The workaround with "Other Parameters" should be ok in this case. Will look into it.

As of syncing docstrings, you just have the two options:

• Sync manually and monitor deviations (--> current tests).
• Any automatic mechanism at build or import-time.

I currently do not oversee the subtleties of the latter, and therefore, cannot comment here.

Docstring / test adapted.

Test passed; you've got .legend in there somewhere, and its ambiguous between Figure.legend and axes.legend.