Issue 1:
Bug report

Bug summary

From a discussion in #10186: The data note inserted in the docstring via @_preprocess_data can be displayed in unexpected places in the generated html documentation.

Examples

in Other Parmeters

in See Also

Reason

I'm not an expert in numpydoc, but from my understanding, this is the issue:

@_preprocess_data just appends an admonition

.. note::
In addition to the above described arguments, this function can take a
**data** keyword argument. If such a **data** argument is given, the

In numpydoc, everything is part of some section. Since @_preprocess_data does not add a section, the admonition belongs to whatever section was last. For sections that are plain top-level such as Notes or Examples, this looks ok (though technically the note is part of the example). It goes wrong for differently formatted or reordered sections (e.g. indented Other Parameters or contained in a See Also box). Example docstring:

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

Solution

To do this correctly, the inserted admonition should always be part of a Notes section. There are diffent ways to achieve this:

Make sure docstrings using @_preprocess_data do always end with a Notes section. Manually add an empty one if there is none.

Let @_preprocess_data add the Notes section. This is not trivial because you may or may not have an Notes section already and duplicated sections are not allowed (numpy/numpydoc#67 could help on this).

Change @_preprocess_data 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 @_preprocess_data could warn if it could not format its note into the docstring). The docstring could look like this:

Notes
-----
{data_note}

There may be other options like extending numpydoc to have an additional custom Data Note section, but I don't think its worth the effort.

For now, I use option 1. as a simple workaround on a case by case basis (also in #10186).

2. would be too much magic.

In the long run, I propose to switch to option 3.

PS

Just got another idea possibly worth considering. If we change to formatting anyway, one could get rid of the admonition and format a custom data entry into the Paramters or Additonal Paramters section:

Parameters
----------
x : array
some text
y : array
other text
{data_param}
color : Color
more params

Issue 2:
As shown by #11094 #12612 matplotlib is used inside of webservers to dynamically serve plots. The example should show:

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 new_figure_manager

saving to a bytesIO buffer to avoid disk

png, svg, and pdf

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