@anntzer The NumpyDoc style guide states, that the Parameters section of the class should detail the constructor arguments, see:
https://numpydoc.readthedocs.io/en/latest/format.html#documenting-classes

This is in accordance with the ecosystem, e.g., using LogLocator? in IPython displays only the class docstring, but not the LogLocator.__init__ docstring which you are interested in. The same goes for using hover of the python-lsp-server.

Personally, I want to know the constructor (__init__) parameters when I request the documentation. This was the reason I created this pull request. Most classes in matplotlib seem to respect the NumpyDoc style.

Duplicating the documentation in __init__ seems harder to maintain, but I'll just go with the convention matplotlib uses.

I don't really want to fight over this (even though I think documenting in __init__ just makes more sense, both in itself and also wrt inheritance), but if we decide to standardize on that, #17029 should be fixed accordingly.

I don't really care, either. But like I said, the NumpyDoc style says put it in the class docstring. Editors act accordingly. So if matplotlib would go against this convention, language servers would have to be changed, which I don't see as an option.

See the attached screenshots, the current situation is really annoying:

hover doesn't give useful information:

I have to write out __init__ instead and hover it, then delete it again:

That's so annoying that I opened the pull request. PercentFormatter is nice, here I just type it and immediately know which parameters I have to add:

Or the rendered version:

P.S.: https://github.com/python-lsp/python-lsp-server was used. If there are other language servers that handle numpydoc differently, please correct me.

@anntzer I think we would need a pretty good reason to not follow the numpydoc standard here, wouldn't we? Breaking in-editor documentation seems bad. I don't quite understand the problem in #17029 - is this a sphinx problem we are working around?

https://matplotlib.org/3.2.0/api/table_api.html#matplotlib.table.Cell is the "wrong" rendering (with doubled parameters docs). I'm not going to block this PR, just pointing out that we should try to avoid this kind of problems...

I'm not going to block this PR,

You are blocking this PR 😉 I agree that we can't have mis-rendered docs, I just wasn't clear if we had mis-rendered docs because of a sphinx bug, or us needing to do the docstring inheritance differently.

https://matplotlib.org/3.2.0/api/table_api.html#matplotlib.table.Cell is the "wrong" rendering (with doubled parameters docs).

It's doubled because we have configured Sphinx to display both class and __init__ docstrings, which has been the case since 2008 apparently. Most likely that's done because we aren't very consistent about putting them in one location. If everything were in e.g., the class docstring, we could reset that option to default (class) and see only one thing.

I'd propose we merge this. Suggest its a bunch of easy first contributions to clean up putting the docstrings in the class def....

As there was some controversy here, we might consider adding some info to the documentation guidelines.

In principle, numpydoc is referred

All new or edited docstrings should conform to the numpydoc docstring guide.

so it should be fine. But if there is confusion, being explicit might be better, even if it is redundant.

I don't know if there is confusion per-se, just that our codebase developed somewhat before numpydoc even existed.

This needs a rebase now.

Note that the numpydoc standard (document __init__ in the class docstring) is violating PEP-257:

The docstring for a class should summarize its behavior and list the public methods and instance variables. [...] The class constructor should be documented in the docstring for its __init__ method.

So we might theoretically break other tools.

TL;DR Overall I'm +0.1 for class-docstring only

Should tools be able to cope with/wo __init__ docstrings? - Yes both

I've tested VSCode and PyCharm; both behave sanely with and without init docstring:

• if init docstring: Show signature + init docstring
• if no init docstring: Show signature + class docstring

Question: Does the python-lsp-server really identify numpydoc style? And then behave differently? I haven't checked but almost cannot belive that. If not they would in general not follow PEP-257. And that should be a reason to change the language server.

Do we want to change?

I'd say not just for the sake of fixing python-lsp-server. IMHO this issue is on them.

Other considerations for class-docstring only

• There's only one place two write everything down. We don't have to rely on sphinx/numpydoc mangling this together in a meaningful way. --> +0.6
• We fix python-lsp-server --> +0.2
• We cannot inherit class and init docstrings independently. -> Possibly a bit more duplication. OTOH individual inheritance can also be unexpected. --> +0.3
• Documenting the init parameters in that method docstring is more natural. --> -1

Overall I'm +0.1 for class-docstring only

I've added this to the call....

@jklymak don't suppose you remember if a decision was reached or documented here?

@dstansby No I don't recall what was decided, if anything.

I propose we merge this and open a new issue to document (and enforce uniformly) where this should go.