RT02 enforces the pandas docstring guide, not the numpydoc docstring guide

[brandondavid]

The RT02 error has the description:

"The first line of the Returns section should contain only the type, unless multiple values are being returned"

This appears to enforce the pandas docstring guide:

"...no name will be provided, unless the method returns or yields more than one value"

In contrast, the numpydoc docstring guide states:

"...the name of each return value is optional. The type of each return value is always required"

This is a concern for SciPy, where the general standard has been to specify the name of all return values, even when only a single value is returned. As a very rough measure, over 42% of the functions in scipy.stats are currently tripping RT02 errors (and that's without bothering to bracket out the functions which return multiple values).

Possible solutions:

1. Update the numpydoc docstring guide to stipulate what RT02 enforces. This would necessitate a lot of little edits (at least for SciPy) and the loss of some potentially valuable information from the documentation.

2. Remove RT02 from numpydoc.validate. But then, pandas either loses that particular validation or has to (re)implement a version of the script in their project, which would be a reversal of the recent effort to bring things from pandas to numpydoc.

3. Or, as a compromise, demote RT02 to a warning, which would only report if specifically requested. If numpydoc doesn't mind maintaining non-numpydoc warnings, a central collection would be convenient for numpydoc users looking for stricter validation. Further, if there is a desire to update the numpydoc docstring guide, collaborating about such warnings would be a great place to start.

[larsoner]

My vote would be to add a --ignore to the eventual command-line option (#240), and probably have this check (and GL01) in the default --ignore.

End-users who use the validation function rather than #240's command line function (SciPy being one of them) can each filter the warnings as they want. It's very simple to do it, and better than implementing filtering schemes at the numpydoc end because you can have finer-grained control on a per-project basis (e.g., when to filter what).

[datapythonista]

and the loss of some potentially valuable information from the documentation.

@brandondavid can you provide an example of this? In pandas we didn't find any case where naming the return, when it's a single value, was useful. If in scipy those names are useful, may be option 2 is the most reasonable (even if it may be annoying for other projects that want to follow this rule).

[rth]

End-users [..] can each filter the warnings as they want. [..] and better than implementing filtering schemes at the numpydoc end because you can have finer-grained control on a per-project basis (e.g., when to filter what).

IMO one of the goals of numpydoc validation tool should be reduce the amount of style decisions the user has to make. I that aspect black is quite good. It would be good to have something comparable for docstrings (at least a linter): apply a tool knowing that someone knowledgeable at numpydoc made the best style decisions (and that I don't have to think about it).

Of course, each project may have special requirements, and some backward compatibility constraints, so it's fine to have a mechanism for those, but it would be better it it was an exception not the norm.

[brandondavid]

My vote would be to add a --ignore to the eventual command-line option (#240), and probably have this check (and GL01) in the default --ignore.

So this is along the lines of option ⋕3 above, which would also be my vote.

But is it concerning that this would put numpydoc into the business of hosting some non-numpydoc warnings? Regardless of whether that's a capped list or an actively curated collection, it exposes a key question -- should the validation script enforce the letter of docstring guide or the reality of how docstrings are typically written now? Is it possible to do both?

[brandondavid]

can you provide an example of this? In pandas we didn't find any case where naming the return, when it's a single value, was useful.

Good point. Now that I'm thinking about it, I'm convinced there aren't any such examples. In fact, not naming single-value returns might be less confusing overall.

But I should tuck in that this is not the only material difference between the pandas docstring guide and the numpydoc docstring guide. Should I make individual issues for those differences or just list them here?

[datapythonista]

In my opinion, the rules in the numpydoc guide and what is validated should be the same.

I think I mentioned earlier, that we were intentionally more strict than the numpydoc standard. If the rest of the community agrees with what we're validating (starting sentences with upper case...), then we should add what is missing to the guide. If people is not happy with a certain validation, then we should probably get rid of it in the validation.

[HealthyPear]

Hello,

not sure if this is the right place to ask for this, but in my code I have something like this,

"""
    Calculate the transit function in the cosine of the zenith angle.

    Parameters
    ----------
    czen : float
        Cosine of the zenith angle.
    dec : `~astropy.units.Quantity`
        Source declination in radians.
    latitude : `~astropy.coordinates.Angle`
        Observatory latitude.

    Returns
    -------
    dt_dcostheta : float
        Variation in time of the source escursion
        in the cosine of the zenith angle.
    """

and I get exactly the error subject of this issue,

WARNING: [numpydoc] Validation warnings while processing docstring for 'pyswgo.irfs.InstrumentResponseGenerator.transit_function_czen':
  RT02: The first line of the Returns section should contain only the type, unless multiple values are being returned

I don't really get what is triggering it...
Is it related to this issue or am I mistaken somewhere?

As far as I know I am using an allowed syntax: https://numpydoc.readthedocs.io/en/latest/format.html#returns

[HealthyPear]

I actually think it's the same issue 😆

[HealthyPear]

BTW (I am performing the validation via sphinx-build if this can be of some help)

[larsoner]

Something like numpydoc_validation_checks = {'all', 'RT02'} in conf.py should allow you to ignore this error in your sphinx build

[HealthyPear]

Yes, I did exactly this as a temporary solution - thanks!