<h3 dir="auto">Documentation Link</h3>
<p dir="auto"><a href="https://matplotlib.org/devdocs/gallery/index.html#examples" rel="nofollow">https://matplotlib.org/devdocs/gallery/index.html#examples</a></p>
<h3 dir="auto">Problem</h3>
<p dir="auto">Folks often go to the gallery looking for an overview of plotting methods, which are in the plot types gallery</p>
<h3 dir="auto">Suggested improvement</h3>
<p dir="auto">Add a sentence to the top of the example gallery page (which is <code class="notranslate">galleries/examples/README.txt</code>) pointing to the plot types gallery, something like</p>
<div class="highlight highlight-text-restructuredtext notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="
For an overview of the plotting methods we provide, see :ref:plot_types"><pre class="notranslate">For an overview of the plotting methods we provide, see <span class="pl-ent">:ref:</span>plot_types</pre></div>
<p dir="auto">This issue is aimed at getting someone comfortable with our doc build and pr process.</p>
<h3 dir="auto">Issue</h3>
<p dir="auto">In <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="263745069" data-permission-text="Title is private" data-url="https://github.com/matplotlib/matplotlib/issues/9324" data-hovercard-type="pull_request" data-hovercard-url="/matplotlib/matplotlib/pull/9324/hovercard" href="https://github.com/matplotlib/matplotlib/pull/9324">#9324</a> I refactored the docstrings for <code class="notranslate">legend.Legend.__init__</code>, <code class="notranslate">figure.Figure.legend</code> and <code class="notranslate">axes.Axes.legend</code>.  In particular, all three have the same kwargs because the two artist versions passthrough kwargs to <code class="notranslate">legend</code>.  All three had different and contradictory/incomplete docstrings.</p>
<p dir="auto">To solve this, I used string interpolation.  The developer docs say:</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="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. "><pre class="notranslate"><code class="notranslate">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. 
</code></pre></div>
<p dir="auto">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:</p>
<div class="highlight highlight-source-python notranslate position-relative overflow-auto" dir="auto" data-snippet-clipboard-copy-content="'''
Parameters
-----------

%(_legend_kw_doc)s
'''"><pre class="notranslate"><span class="pl-s">'''</span>
<span class="pl-s">Parameters</span>
<span class="pl-s">-----------</span>
<span class="pl-s"></span>
<span class="pl-s">%(_legend_kw_doc)s</span>
<span class="pl-s">'''</span></pre></div>
<p dir="auto">Reviewers didn't like this (<a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/NelleV/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/NelleV">@NelleV</a>, <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/anntzer/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/anntzer">@anntzer</a>, <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/tacaswell/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/tacaswell">@tacaswell</a> ) because apparently this sort of interpolation is fragile and has caused issues with the docs in the past:</p>
<blockquote>
<p dir="auto"><a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="176435760" data-permission-text="Title is private" data-url="https://github.com/matplotlib/matplotlib/issues/7095" data-hovercard-type="issue" data-hovercard-url="/matplotlib/matplotlib/issues/7095/hovercard" href="https://github.com/matplotlib/matplotlib/issues/7095">#7095</a>, or <a href="http://matplotlib.org/2.0.0/api/_as_gen/matplotlib.axes.Axes.semilogy.html#matplotlib.axes.Axes.semilogy" rel="nofollow">http://matplotlib.org/2.0.0/api/_as_gen/matplotlib.axes.Axes.semilogy.html#matplotlib.axes.Axes.semilogy</a>, are example of issues caused by uncontrolled interpolation.</p>
</blockquote>
<p dir="auto">For <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="263745069" data-permission-text="Title is private" data-url="https://github.com/matplotlib/matplotlib/issues/9324" data-hovercard-type="pull_request" data-hovercard-url="/matplotlib/matplotlib/pull/9324/hovercard" href="https://github.com/matplotlib/matplotlib/pull/9324">#9324</a> it was decided that we should just cut-and-paste the kwarg docs into the three docstrings.   I also implemented a test in <code class="notranslate">test_legend.py</code> that insured that the docstrings were the same to stop future drift of the docstrings.</p>
<h3 dir="auto">Proper solution?</h3>
<p dir="auto">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.</p>
<h4 dir="auto">Cut-and-paste:</h4>
<p dir="auto">perhaps with unit tests to make sure the docstrings don't drift.</p>
<h4 dir="auto">Structure to hold docstrings:</h4>
<p dir="auto"><a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/anntzer/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/anntzer">@anntzer</a> suggested:</p>
<blockquote>
<p dir="auto">I think we should either use a proper ("structured") interpolation machinery or none at all.</p>
</blockquote>
<p dir="auto">i.e., he suggested a "structured" docstring whereby each section is an <code class="notranslate">OrderedDict</code> entry, and each kwarg is an <code class="notranslate">OrderedDict</code> entry.  This allows referencing of this information in other docstrings.  <a href="https://github.com/matplotlib/matplotlib/issues/9414#issuecomment-336735095" data-hovercard-type="issue" data-hovercard-url="/matplotlib/matplotlib/issues/9414/hovercard">See below</a>.</p>
<h4 dir="auto">Functions to hold docstrings:</h4>
<p dir="auto"><a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/efiring/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/efiring">@efiring</a> <a href="https://github.com/matplotlib/matplotlib/issues/9414#issuecomment-336742969" data-hovercard-type="issue" data-hovercard-url="/matplotlib/matplotlib/issues/9414/hovercard">suggested</a> what is also essentially suggested in <a href="https://matplotlib.org/devel/MEP/MEP10.html" rel="nofollow">MEP10</a> which is that specialized documentation functions be used that have the repeated kwargs, and then the main method's documentation references this.</p>
<h3 dir="auto">Documentation issue</h3>
<p dir="auto">I think the developer docs should make the deprecation of the interpolation machinery explicit if it truly is deprecated.</p>
<h2 dir="auto">Affected functions:</h2>
<ul dir="auto">
<li><code class="notranslate">figure.legend</code> = <code class="notranslate">axes.legend</code> = <code class="notranslate">legend.Legend</code></li>
<li>colorbar?</li>
<li>text properties</li>
</ul>