Support subsections in main description or in notes
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
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).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reviewing how numpydoc handles the main description and Notes section, along with reStructuredText's underline-based section hierarchy. Decide how a subsection marker such as ~~~ could work while preserving plain rst compatibility. Done means subsections render semantically in the supported locations and their hierarchy is unambiguous.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100