numpydoc
numpydoc copied to clipboard
numpy
Don't force 'returns' and 'raises' sections to be definition lists
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.
In [0] the case of the single return value is discussed. You still have to provide a return type, don't you?
[0] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
Yes, but we normally write it in prose rather than a definition list with the type as the term. An example I have open:
Returns
-------
The connection dictionary of the current kernel, as string or dict,
depending on `unpack`.
We do this even though numpydoc doesn't currently render it nicely, because we don't often check the HTML docs when writing docstrings. So I'd rather relax the formatting restriction a little to make this work than try to convince everyone on the team to format docstrings differently.
I guess the question is whether this is any less clear or elegant:
Returns
-------
string or dict
The connection dictionary of the kernel. The type depends on `unpack`.
If you feel it is significantly better and can motivate it, then we should rather update the numpy documentation format.
To my mind, it's less elegant - I'm not defining 'string or dict' as a description of what I'm returning. But I really don't want to start wrangling over documentation standards, I just want to make this tool a bit more flexible so it can cope with what's already the defacto standard in IPython. Maybe it should have a 'strict' parameter that we can turn off if we don't want to exactly follow the numpy doc format.
@takluyver's suggestion of a strict default that can be relaxed by a project is fine with me.
I don't think we want to change the numpy documentation standard itself - consistency is useful.
"strict" is so wide, though, perhaps we can add an "allow" parameter that takes a tuple of strings, which may contain things as "order", "custom_return", etc.
how do we detect this case? By the fact that it's multiline? That seems awkward...
