Don't force 'returns' and 'raises' sections to be definition lists
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
In IPython, the Returns and Raises sections of our docstrings are often a single block of text, not a definition list. In particular, where functions return a single value, it seems awkward to give that value a name in the docstring. However, numpydoc assumes that these sections are always a rst definition list, which results in wonky formatting.
Assuming that other projects want to keep the definition list functionality, I see three ways to achieve this:
- Detect whether the contents look like a definition list (at least two lines, with the second line indented more than the first), and parse the section accordingly.
- Have some attribute on the object that tells numpydoc to parse the docstring differently
- Allow alternative section headings (e.g. 'Return value') which mean the same thing but are parsed differently.
I think 1 feels like the best solution - it's surprising to me that the format of these fields is forced, and I don't think it's too much magic to allow different formats. I'm happy to work on this, but I wanted to discuss it before I started.
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
The issue does not name files, tests, or parser entry points. Start by locating numpydoc's handling of Returns and Raises sections and reading the existing tests for definition-list parsing; done means single-block sections render without definition-list formatting while existing definition-list behavior remains supported.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100