Convention for multi-line type specifications

[jnothman]

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)?

[stefanv]

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

[jorisvandenbossche]

@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

[stefanv]

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)

[jorisvandenbossche]

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).

[stefanv]

We could also parse back-slashes at ends of lines, which would allow the triple quotes to be used.

[jnothman]

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> .

[jnothman]

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> > . >

[anntzer]

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.

[jnothman]

(note that - see #107 - currently parameter lists are not being formatted as definition lists, but i assume that is a historical glitch)

[stefanv]

I have no further ideas on how to handle this one.

[anntzer]

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.

[jnothman]

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??

[stefanv]

Do you mean the HOWTO_DOCUMENT.txt etc.? Or write a short manual for numpydoc (that does seem like a worthwhile thing to do).