numpydoc
numpydoc copied to clipboard
numpy
Convention for multi-line type specifications
Parameter lists allow a specification like:
my_param : type specification
Description
In some cases we at scikit-learn have had long type specifications that overflow into the next line under line-length conventions. From the perspective of documentation rendering, escaping the newline works:
my_param : a really really really really really really really long type \
specification
Description
(This is effective since Python evaluates the string literal and elides the escaped newline at parse time.)
However, PEP257 says:
Use r"""raw triple double quotes""" if you use any backslashes in your docstrings.
So I'm not sure we're doing the right thing. Is there a convention for overflowed type specifications? Should there be one hacked into the numpydoc parser (such as a hanging indent)?
I'd be +1 on parsing indentation that matches the first character of the type description, i.e., something like:
my_param : a really really really really really really really long type
specification
Description
@stefanv That only gives a problem for one character param names (not possible to distinguish between description / overflow of type specification). But of course one character keywords is also bad practice :-)
Anyway, also +1 on a specific guideline (and parsing enhancement) here, as this is something we also regularly have to deal with in pandas
You're right, that's actually quite a common case!
Maybe require a newline after overflow descriptions?
On January 24, 2017 13:06:57 Joris Van den Bossche [email protected] wrote:
@stefanv That only gives a problem for one character param names (not possible to distinguish between description / overflow of type specification). But of course one character keywords is also bad practice :-)
Anyway, also +1 on a specific guideline (and parsing enhancement) here, as this is something we also regularly have to deal with in pandas
-- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: https://github.com/numpy/numpydoc/issues/87#issuecomment-274938680
Also that can give dubious cases / conflicts with current usage. Eg in
a : type
Possible values:
- blabla
- blabla
Although it looks less nice, the extra indent as proposed by @jnothman seems more robust
The extra indent could also be made flexible in number of spaces, so that in practice you can still align it (apart for 1 char param names).
We could also parse back-slashes at ends of lines, which would allow the triple quotes to be used.
There are two problems with that:
- it's brittle when changing the name (e.g. during development)
- it's ambiguous if the parameter name is 1 char, and it often is in scientific python
I'd rather a policy of recognising any consistent overhang relative to the description... but since there's no software-enshrined convention of how far the description should be indented, that might be tricky.
On 25 January 2017 at 07:39, Stefan van der Walt [email protected] wrote:
I'd be +1 on parsing indentation that matches the first character of the type description, i.e., something like:
my_param : a really really really really really really really long type specification Description
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/numpy/numpydoc/issues/87#issuecomment-274931391, or mute the thread https://github.com/notifications/unsubscribe-auth/AAEz6xIj1rUvEKLz6EBw7IpEVR7m5rLUks5rVmFzgaJpZM4Lqj1u .
Sorry, comment posted with lag in reply to Stefan's first comment.
On 25 January 2017 at 09:49, Joel Nothman [email protected] wrote:
There are two problems with that:
- it's brittle when changing the name (e.g. during development)
- it's ambiguous if the parameter name is 1 char, and it often is in scientific python
I'd rather a policy of recognising any consistent overhang relative to the description... but since there's no software-enshrined convention of how far the description should be indented, that might be tricky.
On 25 January 2017 at 07:39, Stefan van der Walt <[email protected]
wrote:
I'd be +1 on parsing indentation that matches the first character of the type description, i.e., something like:
my_param : a really really really really really really really long type specification Description
— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/numpy/numpydoc/issues/87#issuecomment-274931391, or mute the thread https://github.com/notifications/unsubscribe-auth/AAEz6xIj1rUvEKLz6EBw7IpEVR7m5rLUks5rVmFzgaJpZM4Lqj1u .
Right now numpydoc format is actually valid rst (just with some special interpretation of certain markup constructs), e.g. the parameters field is a definition list where the type is a "classifier" (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#definition-lists). I would argue that it is worthwhile to keep this property, which end-of-line backslashes do (they simply do not appear in the string itself), whereas the proposed "recognize indentation" syntax does not.
(note that - see #107 - currently parameter lists are not being formatted as definition lists, but i assume that is a historical glitch)
I think the reference to PEP257 is a misunderstanding, the sentence about raw strings probably refers to the case where the docstring contains a backslash character; but in this case, the backslash only appears in the source as an escape, so I don't think we're violating PEP257...
So I'd just leave things as they are.
I'm happy to go with Antony's suggestion. The key thing to do here is update the documentation.
At some point should we move the docs to live in numpydoc or even be rendered by sphinx??
Do you mean the HOWTO_DOCUMENT.txt etc.? Or write a short manual for numpydoc (that does seem like a worthwhile thing to do).
could combine them, imo. Documenter and installer and developer guide together.
@jorisvandenbossche noted elsewhere that escaping the newline needs to be done without indentation to render correctly in both html and pydoc... but it then looks poor when directly inspecting the source. I suspect we should change the spec to support a hanging indent.
(I'm still in favor of requiring a backslash for the continuation (single backslash if using raw-docstrings, double backslash if not), which has the advantage of avoiding the ambiguity with one-character argument names.)
I think the backslash would be a bit obscure in pydoc, but if that's consensus....
As long as we require descriptions to be indented 4 spaces, we can require that the type spec continuation be indented at least 5.
I don't see why this would look "obscure" in pydoc (and I use pydoc very regularly). Perhaps inelegant at worst, but I don't think it's particularly bad either.
I suggest indenting the type spec continuation 8 spaces (a double indent). That clearly distinguishes it from the description and avoids the hassle of having the indent depend on the length of the parameter name (which is difficult to type initially and difficult to maintain if parameters are renamed).
Was there any solution to this issue?
Unfortunately not. @rossbar, thoughts?
At this point we have two viable solutions on the table: use a backslash, or over-indent the second line. Either seem fine, so we should probably just choose a convention and document it.
Any update here? If not, what indentation is needed to use the backslash with this example?
"""
...
Parameters
----------
...
xi : 2-D ndarray of floats with shape (m, D), or length D tuple of ndarrays broadcastable to the same shape.
Points at which to interpolate data.
...
"""
