Repository navigation
Support subsections in main description or in notes #216
Description
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).
Activity
larsoner commentedon May 1, 2019
Agreed this would be nice, I'm always a little bit sad when I have to do
**Subsection title**.anntzer commentedon May 1, 2019
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.)jnothman commentedon May 2, 2019
anntzer commentedon May 2, 2019
looks like your message was cropped
jnothman commentedon May 2, 2019
The indentation would be a bit disruptive perhaps in pydoc view relative to headings
anntzer commentedon May 2, 2019
.. rubric::is not followed by an indent block, it's basically a standalone title.jnothman commentedon May 2, 2019
larsoner commentedon May 3, 2019
I tested
.. rubric:: Titleand 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.