Convention for multi-line type specifications #87
Comments
|
I'd be +1 on parsing indentation that matches the first character of the type description, i.e., something like: |
|
@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 ***@***.***> 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:
#87 (comment)
|
|
Also that can give dubious cases / conflicts with current usage. Eg in Although it looks less nice, the extra indent as proposed by @jnothman seems more robust |
|
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:
1. it's brittle when changing the name (e.g. during development)
2. 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 ***@***.***> 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
<#87 (comment)>, 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 ***@***.***> wrote:
There are two problems with that:
1. it's brittle when changing the name (e.g. during development)
2. 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 ***@***.***
> 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
> <#87 (comment)>, 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 have no further ideas on how to handle this one. |
|
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.) |
|
The backslash does seem more explicit. |
|
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). |
numpydoc has no guidance for how to handle a long parameter type line. Rearrange things slightly to move the type information to the parameter documentation instead. See numpy/numpydoc#87
numpydoc has no guidance for how to handle a long parameter type line. Rearrange things slightly to move the type information to the parameter documentation instead. See numpy/numpydoc#87
|
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.
...
""" |
Parameter lists allow a specification like:
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:
(This is effective since Python evaluates the string literal and elides the escaped newline at parse time.)
However, PEP257 says:
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)?
The text was updated successfully, but these errors were encountered: