numpy
Support subsections in main description or in notes
It would be nice if it was possible to have subsections either in the "main" description or in the Notes section. Right now Matplotlib just uses bold to delineate such sections (e.g. in https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.plot.html#matplotlib.axes.Axes.plot "plotting labeled data"), which is not so nice semantically.
In theory, rst supports any kind of underlining to mark subsections (and sections), but numpydoc can probably mandate e.g. using ~~~ (or whatever looks nice to the devs). Also, rst just creates the section hierarchy following the order in which the various kinds of underlines occur, so I guess this may be problematic (assuming we want to keep compatibility with plain rst, which I think is nice to have) for subsections in the main description (but fine for the Notes section, at least).
Agreed this would be nice, I'm always a little bit sad when I have to do **Subsection title**.
Actually, now that I look at it, perhaps one can just use either the .. topic:: or the .. rubric:: rst directives (http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic, http://docutils.sourceforge.net/docs/ref/rst/directives.html#rubric) and call it a day without needing specific support from numpydoc. (If so, perhaps this could be suggested in numpydoc's docs, as these directives are not very well-known, I'd say.)
The indentation due to those directives y
On Thu., 2 May 2019, 8:21 am Antony Lee, [email protected] wrote:
Actually, now that I look at it, perhaps one can just use either the .. topic:: or the .. rubric:: rst directives ( http://docutils.sourceforge.net/docs/ref/rst/directives.html#topic, http://docutils.sourceforge.net/docs/ref/rst/directives.html#rubric) and call it a day without needing specific support from numpydoc. (If so, perhaps this could be suggested in numpydoc's docs, as these directives are not very well-known, I'd say.)
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/numpy/numpydoc/issues/216#issuecomment-488459335, or mute the thread https://github.com/notifications/unsubscribe-auth/AAATH273R47XR3GL5JDTXYLPTIJWNANCNFSM4HJSYIBQ .
The indentation would be a bit disruptive perhaps in pydoc view relative to headings
.. rubric:: is not followed by an indent block, it's basically a standalone title.
Ahh right. Not the most transparent of ReST syntaxes, but perfect here. Add it to an example / format documentation and we can delay deciding on more engineering.
I tested .. rubric:: Title and the output for me at least is very similar to **Title**. And .. topic:: did not work because of some complaint about not being in the main body.