How to use Sphinx's autodoc to document a clas

问题:

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'

回答1:

Here are three alternatives:

1. To ensure that __init__() is always documented, you can use autodoc-skip-member in conf.py. Like this:

   def skip(app, what, name, obj, skip, options):
       if name == "__init__":
           return False
       return 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.

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

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

回答2:

You were close. You can use the autoclass_content option in your conf.py file:

autoclass_content = 'both'

回答3:

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:

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