Issue

In #9324 I refactored the docstrings for legend.Legend.__init__, figure.Figure.legend and axes.Axes.legend. In particular, all three have the same kwargs because the two artist versions passthrough kwargs to legend. All three had different and contradictory/incomplete docstrings.

To solve this, I used string interpolation. The developer docs say:

Since matplotlib uses a lot of pass-through kwargs, e.g., in every function that creates 
a line (plot(), semilogx(), semilogy(), etc…), it can be difficult for the new user to know which
kwargs are supported. Matplotlib uses a docstring interpolation scheme to support 
documentation of every function that takes a **kwargs. 

and the code has numerous places where this is used. I used a simple form of this that hard-coded the kwarg doc string and then invoked it in the three docstrings:

'''
Parameters
-----------

%(_legend_kw_doc)s
'''

Reviewers didn't like this (@NelleV, @anntzer, @tacaswell ) because apparently this sort of interpolation is fragile and has caused issues with the docs in the past:

#7095, or http://matplotlib.org/2.0.0/api/_as_gen/matplotlib.axes.Axes.semilogy.html#matplotlib.axes.Axes.semilogy, are example of issues caused by uncontrolled interpolation.

For #9324 it was decided that we should just cut-and-paste the kwarg docs into the three docstrings. I also implemented a test in test_legend.py that insured that the docstrings were the same to stop future drift of the docstrings.

Proper solution?

So, what is the proper solution to the documentation problem of repeating passthrough kwargs? I didn't see that the substitution decorator was so bad, but I've not seen all the problems.

Cut-and-paste:

perhaps with unit tests to make sure the docstrings don't drift.

Structure to hold docstrings:

@anntzer suggested:

I think we should either use a proper ("structured") interpolation machinery or none at all.

i.e., he suggested a "structured" docstring whereby each section is an OrderedDict entry, and each kwarg is an OrderedDict entry. This allows referencing of this information in other docstrings. See below.

Functions to hold docstrings:

@efiring suggested what is also essentially suggested in MEP10 which is that specialized documentation functions be used that have the repeated kwargs, and then the main method's documentation references this.

Documentation issue

I think the developer docs should make the deprecation of the interpolation machinery explicit if it truly is deprecated.

Affected functions:

• figure.legend = axes.legend = legend.Legend
• colorbar?
• text properties