search

numpy / numpydoc

Numpy's Sphinx extensions
https://numpydoc.readthedocs.io/
Other
294 stars 160 forks source link

GL01 catches valid docstring example #574

Open stefanv opened 2 months ago

stefanv commented 2 months ago 
def my_func():
   """Docstring on first line.

   Should be totally fine.
   """
   ...
stefanv commented 2 months ago

@rossbar It seems like numpydoc validate has been catching this "error" for a long time, but in my mind it's definitely not a mistake to start the docstring on the line of the triple quotes. Looks like it was an artifact brought over from a Pandas style preference?

Will fix up the tests if we decide this is the right way forward.

rossbar commented 2 months ago

This is one of those things that's totally subjective and not really useful IMO, but it's been there since validation was introduced so :shrug:

stefanv commented 2 months ago

What options are available to us?

I'd love to see this rule disabled by default, since it is not in alignment with the NumPy docstring format, which I consider to be the gospel for this tool.

rossbar commented 1 month ago

What options are available to us?

Well, it could be removed outright. Personally I'd be in favor of that - not only for this rule, but for many of the more nitty "rules" that don't actually have anything to do with numpydoc. IMO these types of things are best left to other doc linting tools (e.g. pydocstyle, though that doesn't seem to be actively supported any longer).

The non-breaking way would be to recommend users not use this rule - there are hooks for all the user APIs (pre-commit, sphinx conf, etc.) to ignore certain rules.

stefanv commented 1 month ago

I'd be fine with removing them, or packaging them as optional nitpick rules that can be enabled (but that are disabled by default). But the job here really is to ensure that docs confirm with the numpydoc standard (and not to venture much beyond that).