René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"The data decorator does not integrate well with numpydoc","articleBody":"### Bug report\r\n\r\n**Bug summary**\r\nFrom 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.\r\n\r\n**Examples**\r\n- in [Other Parmeters](https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.errorbar.html#matplotlib.axes.Axes.errorbar)\r\n- in [See Also](https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.vlines.html#matplotlib.axes.Axes.vlines)\r\n\r\n**Reason**\r\nI'm not an expert in numpydoc, but from my understanding, this is the issue:\r\n\r\n-  `@_preprocess_data`  just appends an admonition\r\n  ~~~\r\n  .. note::\r\n      In addition to the above described arguments, this function can take a\r\n      **data** keyword argument. If such a **data** argument is given, the\r\n  ~~~\r\n\r\n- 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:\r\n\r\n~~~\r\nSee Also\r\n--------\r\nfill_betweenx : Fill between two sets of x-values.\r\n\r\n.. note::\r\n    In addition to the above described arguments, this function can take a\r\n    **data** keyword argument. If such a **data** argument is given, the\r\n~~~\r\n\r\n**Solution**\r\nTo do this correctly, the inserted admonition should always be part of a *Notes* section. There are diffent ways to achieve this:\r\n\r\n1. Make sure docstrings using `@_preprocess_data` do always end with a *Notes* section. Manually add an empty one if there is none.\r\n2. 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 (https://github.com/numpy/numpydoc/pull/67 could help on this).\r\n3. 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:\r\n  ~~~\r\n  Notes\r\n  -----\r\n  {data_note}\r\n  ~~~\r\n\r\nThere may be other options like extending numpydoc to have an additional custom *Data Note* section, but I don't think its worth the effort.\r\n \r\nFor now, I use option 1. as a simple workaround on a case by case basis (also in #10186).\r\n2. would be too much magic.\r\nIn the long run, I propose to switch to option 3.\r\n\r\n**PS**\r\nJust 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:\r\n\r\n~~~\r\nParameters\r\n----------\r\nx : array\r\n    some text\r\ny : array\r\n    other text\r\n{data_param}\r\ncolor : Color\r\n    more params   \r\n~~~\r\n\r\n\r\n\r\n  ","author":{"url":"https://github.com/timhoffm","@type":"Person","name":"timhoffm"},"datePublished":"2018-01-07T11:31:56.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":6},"url":"https://github.com/10189/matplotlib/issues/10189"}