Feature request: Automatic docstring generation for classes

[CsatiZoltan]

Automatic docstring generation for functions is very useful and has already been implemented in #4936. Could it be done for classes too?

[ccordoba12]

Could it be done for classes too?

What do you mean by this? Class methods are like functions, so you can have wutomatic docstring generation for them too.

[CsatiZoltan]

I do not mean class methods but docstring template for classes themselves (listing the attributes, etc.). See an example here.

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring).

Source: PEP 257.

[ccordoba12]

@ok97465 , do you think this is possible?

[ok97465]

It doesn't seem to be supported by Pycharm or VsCode's autodocstring, and it doesn't seem to be easy to implement.

However, I would like to consider how to implement it later.

I'll be a little busy for the next two weeks. So I think I'll be able to answer in two weeks later.

[CAM-Gerlach]

I've thought about adding this myself, and PR #25558 would make it easier, but I'm not totally sure how broadly useful it would be, other than avoiding having to manually move the docstring generated on __init__ to the class.

Other than that, it could extract and list class or instance attributes and their types, although that is much less necessary than it once was because they can both be assigned "docstrings" directly and documentation tools will recognize and build them, which helps keep the documentation and code together; and avoids busywork and mistakes having to update the attribute lists and keep them in sync. It could be done, but to keep them in sync we'd need granular integration/updating of existing docstrings on the level of the individual param/exception/attribute level, and that would be quite tricky as the user could have intentionally modified the type, default value, or presence/absence of attributes in their docstrings versus their code for readability or other reasons.

For reference, Googledoc recommends an Attributes list ("should have"), Numpydoc implies it is optional ("may be used") though elsewhere refers to using the aforementioned "docstring" functionality for constants, while native Sphinx doc does not specify it (and would seem to favor using autodoc/apidoc to generate the list, or "docstrings"). FWIW, in Spyder's own (Numpydoc) docstrings we generally document attributes with "docstrings" where they are defined, rather than manually maintaining a separate list in the class docstring.

As for listing class methods, Numpydoc actively recommends against it except for a few user-selected methods in special cases, Googledoc doesn't specify it at all and once again for Sphinxdoc autosummary, apidocs or autodocs would be used instead to generate the list automatically rather than manual scraping.

So, at minimum such a feature could at least automatically generate a docstring for the __init__ on the class (or if it doesn't have one, fall back to a one-line or basic multi-line docstrings), with perhaps a followup PR adding an optional setting to also extract public class and instance attributes and list them under an attributes section appropriate to the current docstring format. However, as I have a lot of other work on my plate (including resolving other docstring generation bugs and issues), and due to limited medium-term funding for Spyder am looking for another funded role, I can't promise I'll get to it myself anytime soon so PRs welcome!