python - 如何使用 Sphinx 的 autodoc 来记录类的 __init__(self) 方法？

Question

默认情况下，Sphinx 不会为 __init__(self) 生成文档。我尝试了以下方法:

.. automodule:: mymodule
    :members:

和

..autoclass:: MyClass
    :members:

在 conf.py 中，设置以下内容仅将 __init__(self) 文档字符串附加到类文档字符串(the Sphinx autodoc documentation 似乎同意这是预期的行为，但没有提及我要解决的问题) :

autoclass_content = 'both'

Answer 1

这里有三种选择:

1. 为确保始终记录 __init__()，您可以使用 autodoc-skip-member在 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. special-members选项是 added in Sphinx 1.1 .它使“特殊”成员(名称如 __special__ 的成员)由 autodoc 记录。

   自 Sphinx 1.2 起，此选项采用参数，使其比以前更有用。

3. 使用自动方法:

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

   这必须为每个类添加(不能与 automodule 一起使用，正如对此答案第一版的评论中指出的那样)。