如何使用Sphinx的autodoc来记录类的初始化（self）方法？

Question

默认情况下，Sphinx不会为初始化（self）生成文档。我试过以下方法：

.. automodule:: mymodule
    :members:

以及

..autoclass:: MyClass
    :members:

在conf.py中，设置以下内容只会将“初始化”（self）docstring附加到类docstring（the Sphinx autodoc documentation似乎同意这是预期的行为，但没有提到我试图解决的问题）：

autoclass_content = 'both'

Answer 1

在过去的几年中，我为各种不相关的Python项目编写了autodoc-skip-member回调的几个变体，因为我希望像__init__()、__enter__()和__exit__()这样的方法出现在我的API文档中（毕竟，这些“特殊方法”是API的一部分，有什么地方比在特殊方法的docstring中更好地记录它们）。

最近，我把最好的实现作为我的一个Python项目（here's the documentation）的一部分。The implementation基本上可以归结为：

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

是的，有比逻辑更多的文档：-）。与使用special-members选项（对我来说）相比，定义这样的autodoc-skip-member回调的好处是special-members选项还支持__weakref__（可用于所有新样式类，AFAIK）等属性的文档，我认为这些属性是噪音，根本没有用处。回调方法避免了这一点（因为它只对函数/方法起作用，而忽略其他属性）。

Answer 2

你很亲密。您可以在conf.py文件中使用^{}选项：

autoclass_content = 'both'

Answer 3

这里有三种选择：

1. 为了确保始终记录__init__()，可以在conf.py中使用^{}。像这样：

   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)
   

   这明确定义了__init__不能被跳过（默认情况下是这样的）。此配置只指定一次，对于.rst源中的每个类，它不需要任何附加标记。

2. ^{}选项是added in Sphinx 1.1。它使“特殊”成员（那些名字像__special__）由autodoc记录下来。

   由于Sphinx 1.2，此选项采用参数，因此比以前更有用。

3. 使用automethod：

   .. autoclass:: MyClass     
      :members: 
   
      .. automethod:: __init__
   

   必须为每个类添加此项（不能与automodule一起使用，如本答案第一次修订的注释中所指出的）。