GL01 catches valid docstring example

[stefanv]

def my_func():
   """Docstring on first line.

   Should be totally fine.
   """
   ...

[stefanv]

@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]

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 🤷

[stefanv]

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]

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]

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

[stefanv]

I'd be glad to get this in @rossbar @larsoner. I think important for our default warnings to be in alignment with the specification.

[larsoner]

This seems like a bugfix for me. Looks like in MNE-Python we've been ignoring GL01 for exactly this reason. It'll be nice to reenable it!