Allow separate documentation for class and `__init__` constructor

[carlosgmartin]

Context here.

It would be nice to be able to separately document a class and its __init__ constructor.

This could potentially be done by adding an extra option to autoapi_python_class_content, say separate.

[Reylak]

I also want this exact behavior.

It seems that Napoleon would be able to do that using napoleon_include_init_with_doc.

With this configuration:

napoleon_include_init_with_doc=True
autoapi_python_class_content = "class"
autoclass_content = "class"

I only get the parameters list in the class doc (and without the doc of the parameters that is given in the init docstring).
With "both" for the _content options, I get the init's docstring and the docs of the parameters in the class doc.

I would expect autoapi to honor Napoleon's napoleon_include_init_with_doc, and that the configuration I gave just above produces a separate docstring for __init__ (and no parameters doc in the class doc).
But to be fair, I have no idea how all Sphinx's extensions are supposed to honor each other's options regarding the "structure" of the doc.

[Reylak]

(adding my rationale as another comment)

I like to document the class's general behavior and usage in its docstring, but document peculiarities of its initialization (interaction between parameters, special or non obvious meanings of them, etc.) in the __init__'s docstring.

Parameters to __init__ ultimately affect the instance, not the class itself.

Note that this is orthogonal even to the initial issue linked in this issue, where the problem was about merging the documentation of attributes from the class's docstring, with the extracted information about attributes from its __init__.

[bkeryan]

I like to document the class's general behavior and usage in its docstring, but document peculiarities of its initialization (interaction between parameters, special or non obvious meanings of them, etc.) in the __init__'s docstring.

I also want this behavior for the same reason.

One other twist: I previously documented the class's general behavior and usage in the module docstring, but the module in question defines multiple classes, so I set autoapi_own_page_level = "class" to split each class into a separate page. Now the class page has the title and constructor signature at the top and I don't see a way to include additional content above the constructor signature without adding more modules, switching to autodoc-style directives, or something similar. More details here: ni/nitypes-python#155

[AWhetter]

Since 6ca62f1, We specifically skip __init__ from being output (

sphinx-autoapi/autoapi/_objects.py

Line 319 in ccb2e89

"__init__",

). It's done that way to mirror the behaviour of autodoc:

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content

In case of AutoAPI, you can connect to the autoapi-skip-member event and configure it unskip __init__ methods.

We should add a note about this to the docs here and maybe also here.