Repository navigation
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
Activity
anntzer commentedon Jan 7, 2018
I vote for the PS option (format a custom data entry).
tacaswell commentedon Jan 7, 2018
The decorator used to add a
Notessection at the bottom which was the trigger for numpy/numpydoc#65Putting the information in Parameters or Other Parameters is best, not sure the right way to do that though.
Putting in a templatting string in works but requires coordination between two places (the decorator and the docstring). Having the decorator parse the docstring as numpydoc, insert the lines and then write it back out is also an option, but I am not sure what the start-up time cost of that is. We already have some pretty significant docstring templating going on (and discussions about removing it) so I am not sure that the net run-time cost will be that large.
Another option is a helper that just re-writes the source to extend the docstring, but that is probably the worst of all worlds.
timhoffm commentedon Jan 7, 2018
Why not?
That's true, but the decorator can easily check if it could modify the docstring using formatting and warn otherwise.
timhoffm commentedon Jan 10, 2018
Until this is resolved, I will use an empty Notes section with a standard comment.
This will make a possible later migration easier.
dstansby commentedon Apr 29, 2019
Looks like this will be fixed by #14029
timhoffm commentedon Apr 29, 2019
Fixed by #14029.