Allow param lists to split on ': ' rather than ' : '

[jnothman]

It is very easy to mistakenly separate parameter names from their type description by ': ' instead of the correct ' : '. There are at least 260 instances in Scikit-learn, for instance, and Joblib appears to use : without a preceding space as a standard. This variation is unsurprising when See Also, for instance, does not require a space before its colons.

Would we expect great ramifications were we to change it to allow a single colon followed by whitespace as delimiter?

[jnothman]

Ping @scikit-learn

[stefanv]

How about we split correctly but issue a warning?

[jnothman]

See, by the way, my attempt (via grep, sed, git apply, git add --patch) to fix such errors in scikit-learn at https://github.com/scikit-learn/scikit-learn/pull/7920

I considered a warning, and don't mind it. I'd actually rather something that output a git patch :) Main problem is that I don't think NumpyDocstring has enough context information to make the warning very informative.

[stefanv]

That grep script is truly horrific ;)

[jnothman]

I did try implementing it in numpydoc, but got sick at the thought of putting all the context info in.

This worked :)

[stefanv]

So, if you have something that works, would fixing numpydoc still be useful to you, or should we just add that "fixer" into the README?

[jnothman]

I think fixing numpydoc is worthwhile. I wanted a way to resolve these quickly so that we can then use numpydoc to check for inconsistencies between signature and docstrings.

On 23 November 2016 at 09:52, Stefan van der Walt [email protected] wrote:

So, if you have something that works, would fixing numpydoc still be useful to you, or should we just add that "fixer" into the README?

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/numpy/numpydoc/issues/78#issuecomment-262390063, or mute the thread https://github.com/notifications/unsubscribe-auth/AAEz62wrbGFfo-Wr74W5XcbYkNK4TWy7ks5rA3IdgaJpZM4K4qEh .

[stefanv]

I think this and other discussions around similar requests has helped settle the issue in my mind: we should stick to one docstring format, and rather help those who want to fix their projects with a linter-type tool.

[jnothman]

The problem with that statement is that the docstring format is somewhat inconsistent: see also allows leading space or none; parameters allows with leading space only.

[jnothman]

But yes, I'm happy with a linter/fixer.

[stefanv]

The docstring format seems consistent? https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

[jnothman]

But the implementation is not similarly restrictive: https://github.com/numpy/numpydoc/blob/master/numpydoc/docscrape.py#L255

On 23 November 2016 at 12:42, Stefan van der Walt [email protected] wrote:

The docstring format seems consistent? https://github.com/numpy/ numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/numpy/numpydoc/issues/78#issuecomment-262416826, or mute the thread https://github.com/notifications/unsubscribe-auth/AAEz605jA4bkSoRCM1srNv1e9fEiMCeQks5rA5oOgaJpZM4K4qEh .

[jnothman]

I'll submit a PR for a linter/fixer.

[stefanv]

Thanks @jnothman, I'd be happy to review that.

[anntzer]

I think the original proposal should be rejected for the same reason as mentioned in https://github.com/numpy/numpydoc/issues/87#issuecomment-328224912 (+ following discussion).