numpy / numpy/numpydoc

Don't force 'returns' and 'raises' sections to be definition lists

Open
#20 8 comments 0 reactions 0 assignees View on GitHub

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:

  1. 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.
  2. Have some attribute on the object that tells numpydoc to parse the docstring differently
  3. 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.