Description
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_datajust 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_datadoes 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_datado always end with a Notes section. Manually add an empty one if there is none. - Let
@_preprocess_dataadd the Notes section. This is not trivial because you may or may not have an Notes section already and duplicated sections are not allowed (ENH: merge duplicate sections (rather than raise) numpy/numpydoc#67 could help on this). - Change
@_preprocess_datato 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_datacould 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