<h3 dir="auto">Bug report</h3>
<p dir="auto"><strong>Bug summary</strong><br>
From a discussion in <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="286538675" data-permission-text="Title is private" data-url="https://github.com/matplotlib/matplotlib/issues/10186" data-hovercard-type="pull_request" data-hovercard-url="/matplotlib/matplotlib/pull/10186/hovercard" href="https://github.com/matplotlib/matplotlib/pull/10186">#10186</a>: The data note inserted in the docstring via <code class="notranslate">@_preprocess_data</code> can be displayed in unexpected places in the generated html documentation.</p>
<p dir="auto"><strong>Examples</strong></p>
<ul dir="auto">
<li>in <a href="https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.errorbar.html#matplotlib.axes.Axes.errorbar" rel="nofollow">Other Parmeters</a></li>
<li>in <a href="https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.vlines.html#matplotlib.axes.Axes.vlines" rel="nofollow">See Also</a></li>
</ul>
<p dir="auto"><strong>Reason</strong><br>
I'm not an expert in numpydoc, but from my understanding, this is the issue:</p>
<ul dir="auto">
<li><code class="notranslate">@_preprocess_data</code>  just appends an admonition</li>
</ul>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content=".. note::
    In addition to the above described arguments, this function can take a
    **data** keyword argument. If such a **data** argument is given, the"><pre class="notranslate"><code class="notranslate">.. note::
    In addition to the above described arguments, this function can take a
    **data** keyword argument. If such a **data** argument is given, the
</code></pre></div>
<ul dir="auto">
<li>In numpydoc, everything is part of some section. Since  <code class="notranslate">@_preprocess_data</code> does not add a section, the admonition belongs to whatever section was last. For sections that are plain top-level such as <em>Notes</em> or <em>Examples</em>, this looks ok (though technically the note is part of the example). It goes wrong for differently formatted or reordered sections (e.g. indented <em>Other Parameters</em> or contained in a <em>See Also</em> box). Example docstring:</li>
</ul>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="See Also
--------
fill_betweenx : Fill between two sets of x-values.

.. note::
    In addition to the above described arguments, this function can take a
    **data** keyword argument. If such a **data** argument is given, the"><pre class="notranslate"><code class="notranslate">See Also
--------
fill_betweenx : Fill between two sets of x-values.

.. note::
    In addition to the above described arguments, this function can take a
    **data** keyword argument. If such a **data** argument is given, the
</code></pre></div>
<p dir="auto"><strong>Solution</strong><br>
To do this correctly, the inserted admonition should always be part of a <em>Notes</em> section. There are diffent ways to achieve this:</p>
<ol dir="auto">
<li>Make sure docstrings using <code class="notranslate">@_preprocess_data</code> do always end with a <em>Notes</em> section. Manually add an empty one if there is none.</li>
<li>Let <code class="notranslate">@_preprocess_data</code> add the <em>Notes</em> section. This is not trivial because you may or may not have an <em>Notes</em> section already and duplicated sections are not allowed (<a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="183279612" data-permission-text="Title is private" data-url="https://github.com/numpy/numpydoc/issues/67" data-hovercard-type="pull_request" data-hovercard-url="/numpy/numpydoc/pull/67/hovercard" href="https://github.com/numpy/numpydoc/pull/67">numpy/numpydoc#67</a> could help on this).</li>
<li>Change <code class="notranslate">@_preprocess_data</code> to not append someting, but format.  Advantage: This is more explicit and prevents surprises. Disadavantage: The documenter has to know that the note has to be added and do it manually (But at least <code class="notranslate">@_preprocess_data</code> could warn if it could not format its note into the docstring). The docstring could look like this:</li>
</ol>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="Notes
-----
{data_note}"><pre class="notranslate"><code class="notranslate">Notes
-----
{data_note}
</code></pre></div>
<p dir="auto">There may be other options like extending numpydoc to have an additional custom <em>Data Note</em> section, but I don't think its worth the effort.</p>
<p dir="auto">For now, I use option 1. as a simple workaround on a case by case basis (also in <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="286538675" data-permission-text="Title is private" data-url="https://github.com/matplotlib/matplotlib/issues/10186" data-hovercard-type="pull_request" data-hovercard-url="/matplotlib/matplotlib/pull/10186/hovercard" href="https://github.com/matplotlib/matplotlib/pull/10186">#10186</a>).<br>
2. would be too much magic.<br>
In the long run, I propose to switch to option 3.</p>
<p dir="auto"><strong>PS</strong><br>
Just got another idea possibly worth considering. If we change to formatting anyway, one could get rid of the admonition and format a custom <em>data</em> entry into the <em>Paramters</em> or <em>Additonal Paramters</em> section:</p>
<div class="snippet-clipboard-content notranslate position-relative overflow-auto" data-snippet-clipboard-copy-content="Parameters
----------
x : array
    some text
y : array
    other text
{data_param}
color : Color
    more params   "><pre class="notranslate"><code class="notranslate">Parameters
----------
x : array
    some text
y : array
    other text
{data_param}
color : Color
    more params   
</code></pre></div>
<p dir="auto">As shown by <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="316339179" data-permission-text="Title is private" data-url="https://github.com/matplotlib/matplotlib/issues/11094" data-hovercard-type="issue" data-hovercard-url="/matplotlib/matplotlib/issues/11094/hovercard" href="https://github.com/matplotlib/matplotlib/issues/11094">#11094</a> <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="373384618" data-permission-text="Title is private" data-url="https://github.com/matplotlib/matplotlib/issues/12612" data-hovercard-type="issue" data-hovercard-url="/matplotlib/matplotlib/issues/12612/hovercard" href="https://github.com/matplotlib/matplotlib/issues/12612">#12612</a> matplotlib is used inside of webservers to dynamically serve plots.  The example should show:</p>
<ol dir="auto">
<li>importance of picking a non-GUI backend (both by setting the backend and explicitly by not using pyplot).  Given that these servers are multi-threaded, not using pyplot at all may be the best option to avoid any coupling between workers via pyplot and memory leaks due to pyplot holding references to figures forever.  Should probably show use of <code class="notranslate">new_figure_manager</code></li>
<li>saving to a bytesIO buffer to avoid disk</li>
<li>png, svg, and pdf</li>
<li>be applicable to both django and flask (not sure off the top of my head what the differences are), bonus points for cherrypy, aiohttp, tornado, and pyramid</li>
</ol>