How to use Sphinx's autodoc to document a class's __init__(self) method?
Solution 1
Here are three alternatives:
-
To ensure that
__init__()
is always documented, you can useautodoc-skip-member
in conf.py. Like this:def skip(app, what, name, obj, would_skip, options): if name == "__init__": return False return would_skip def setup(app): app.connect("autodoc-skip-member", skip)
This explicitly defines
__init__
not to be skipped (which it is by default). This configuration is specified once, and it does not require any additional markup for every class in the .rst source. -
The
special-members
option was added in Sphinx 1.1. It makes "special" members (those with names like__special__
) be documented by autodoc.Since Sphinx 1.2, this option takes arguments which makes it more useful than it was previously.
-
Use
automethod
:.. autoclass:: MyClass :members: .. automethod:: __init__
This has to be added for every class (cannot be used with
automodule
, as pointed out in a comment to the first revision of this answer).
Solution 2
You were close. You can use the autoclass_content
option in your conf.py
file:
autoclass_content = 'both'
Solution 3
Even though this is an older post, for those who are looking it up as of now, there is also another solution introduced in version 1.8. According to the documentation, You can add the special-members
key in the autodoc_default_options
to your conf.py
.
Example:
autodoc_default_options = {
'members': True,
'member-order': 'bysource',
'special-members': '__init__',
'undoc-members': True,
'exclude-members': '__weakref__'
}
Solution 4
Over the past years I've written several variants of autodoc-skip-member
callbacks for various unrelated Python projects because I wanted methods like __init__()
, __enter__()
and __exit__()
to show up in my API documentation (after all, these "special methods" are part of the API and what better place to document them than inside the special method's docstring).
Recently I took the best implementation and made it part of one of my Python projects (here's the documentation). The implementation basically comes down to this:
import types
def setup(app):
"""Enable Sphinx customizations."""
enable_special_methods(app)
def enable_special_methods(app):
"""
Enable documenting "special methods" using the autodoc_ extension.
:param app: The Sphinx application object.
This function connects the :func:`special_methods_callback()` function to
``autodoc-skip-member`` events.
.. _autodoc: http://www.sphinx-doc.org/en/stable/ext/autodoc.html
"""
app.connect('autodoc-skip-member', special_methods_callback)
def special_methods_callback(app, what, name, obj, skip, options):
"""
Enable documenting "special methods" using the autodoc_ extension.
Refer to :func:`enable_special_methods()` to enable the use of this
function (you probably don't want to call
:func:`special_methods_callback()` directly).
This function implements a callback for ``autodoc-skip-member`` events to
include documented "special methods" (method names with two leading and two
trailing underscores) in your documentation. The result is similar to the
use of the ``special-members`` flag with one big difference: Special
methods are included but other types of members are ignored. This means
that attributes like ``__weakref__`` will always be ignored (this was my
main annoyance with the ``special-members`` flag).
The parameters expected by this function are those defined for Sphinx event
callback functions (i.e. I'm not going to document them here :-).
"""
if getattr(obj, '__doc__', None) and isinstance(obj, (types.FunctionType, types.MethodType)):
return False
else:
return skip
Yes, there's more documentation than logic :-). The advantage of defining an autodoc-skip-member
callback like this over the use of the special-members
option (for me) is that the special-members
option also enables documentation of properties like __weakref__
(available on all new-style classes, AFAIK) which I consider noise and not useful at all. The callback approach avoids this (because it only works on functions/methods and ignores other attributes).
Solution 5
As long as this commit approved: https://github.com/sphinx-doc/sphinx/pull/9154, in the next sphinx version (>4.1.2) will be possible to:
..autoclass:: MyClass1
:members:
:class-doc-from: "class"
..autoclass:: MyClass2
:members:
:class-doc-from: "init"
allendom
Updated on August 18, 2021Comments
-
allendom almost 3 years
Sphinx doesn't generate docs for __init__(self) by default. I have tried the following:
.. automodule:: mymodule :members:
and
..autoclass:: MyClass :members:
In conf.py, setting the following only appends the __init__(self) docstring to the class docstring (the Sphinx autodoc documentation seems to agree that this is the expected behavior, but mentions nothing regarding the problem I'm trying to solve):
autoclass_content = 'both'
-
Roger Binns almost 13 yearsThat doesn't help with automodule since it has to be added to every class.
-
jcarballo almost 11 yearsThe first alternative worked. In my case it was better than the second and third alternatives, as it doesn't need to be editing .rst files.
-
Florian Brucker almost 10 yearsIn Sphinx 1.2.1,
special-members
works fine usingautomodule
. Use:special-members: __init__
to document only__init__
. -
László Papp almost 10 years@MichaelMrozek: I am wondering about that, too... Did you understand the high upvote rate of this answer? At first, it looks like an answer that should be purged.
-
Stretch about 9 yearsI tried setting the
autoclass_content = 'both'
option, which did document the init method, but it made the autosummary appear twice. -
oarfish almost 6 yearsHow do I use this? It seems the method must be named
setup(app)
in order to be executed by Sphinx. -
Andrew about 5 yearsI don't understand it all, but see xolox's implementation if you want to dissect yourself. I believe he built a sphinx extension that connects a callback to the autodoc-skip-member event. When sphinx tries to figure out if something should be included/skipped that event fires, and his code runs. If his code detects a special member that was defined explicitly by the user (inherited like often happens) then it tells Sphinx to include it. That way you can doc special members you write yourself
-
xolox about 5 yearsThanks for the clarifications Andrew and yes you are correct oarfish, a setup function is needed. I've added it to the example to avoid further confusion.
-
xolox over 4 years@JoelB: The example code in my post is written to assume that your
__init__
method has a nonempty docstring. Does it? -
BerriJ about 4 yearsThis should be the accepted answer. It is simpler and it refers to the official sphinx documentation.
-
Terseus over 3 yearsThis is the best way to do it, it works perfectly with autosummary and the result it's much better than
special-methods
, the former add the constructor doc right at the start of the class and the latter adds a separate__init__
method to the doc. -
niid over 2 yearsAs usual with stackoverflow, the best answer is at the bottom oft the page.