自动摘要生成的文档缺少除“__init__”之外的所有 dunder 方法

Question

我正在使用 Sphinx 的自动摘要为模块的每个成员自动生成单独的第一个文件。文档按预期创建，只是生成的第一个文件缺少除__init__.

在我的conf.py我有以下几行：

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
]

autosummary_generate = True
autosummary_imported_members = True

考虑下面的虚拟类，它包含 dunder 和常规公共方法：

class MyClassA:

    def __init__(self):
        r'__init__ docstring'
        pass

    def __call__(self):
        r'__call__ docstring'
        pass

    def __len__(self):
        r'__len__ docstring'
        pass

    def public_method_1(self):
        r'public_method_1 docstring'
        pass

    def public_method_2(self):
        r'public_method_2 docstring'
        pass

在我的第一个主文件中，我设置了自动摘要，如下所示：

.. autosummary::
    :toctree: my_module_members

    my_module.MyClassA
    my_module.MyClassB

/my_module_members正如预期的那样，自动摘要会为模块的每个成员创建一个以单独的第一个文件命名的子目录。但仅__init__在这些自动生成的第一个文件的“方法”部分中列出。例如：

my_module.MyClassA
==================

.. currentmodule:: my_module

.. autoclass:: MyClassA




   .. rubric:: Methods

   .. autosummary::

      ~MyClassA.__init__
      ~MyClassA.public_method_1
      ~MyClassA.public_method_2

因此，在生成的 html 文档中，方法表中仅列出了这三个方法，而没有 和__call__：__len__

所以我的问题是，以这种方式使用自动摘要时如何包含所有特殊方法？

Answer 1

问题在于自动摘要用于类的默认模板。这是文档中的相关页面，但直接查看默认模板更有帮助：

# In the sphinx v3.0.4 source code:
# sphinx/ext/autosummary/templates/autosummary/class.rst
{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}

   {% block methods %}
   .. automethod:: __init__

   {% if methods %}
   .. rubric:: Methods

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: Attributes

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

您可以看到此模板如何与为您的项目生成的存根文件相对应（尽管我不确定为什么您的模板缺少该行.. automethod:: __init__；也许我们有不同版本的 sphinx）。重要的部分是{% for item in methods %}循环。上面链接的文档简要提到methods仅包含“公共”方法，这意味着不以下划线开头的方法。 __init__()根据 的第 242 行，也被认为是公开的sphinx/ext/autosummary/generate.py，尽管这似乎没有在任何地方记录。希望这能解释您所看到的行为。

考虑到这一点，我可以想到三种方法将所有特殊方法包含在文档中：

1. members提供使用而不是 的自定义模板methods。这应该记录所有内容，但会消除方法、属性、继承成员、内部类等之间的区别。

2. 这没有记录，我也没有尝试过，看起来您可以替换methods为all_methods以包含自动摘要中的所有方法（再次参见第 242 行）。不过，公共方法和私有方法之间没有任何区别。

3. 尝试使用autoclasstoc。全面披露：这是我编写的一个包，旨在更好地总结 sphinx 文档中的类方法。它比自动摘要更具可配置性，并且默认情况下包含每个方法。它还折叠了继承的方法，这对于大类来说非常好，尽管这可能与您相关，也可能不相关。

   本页描述了如何将 autoclasstoc 与 autosummary 结合使用，但要点是您需要一个如下所示的自定义模板：

   {{ fullname | escape | underline}}
   
   .. currentmodule:: {{ module }}
   
   .. autoclass:: {{ objname }}
      :members:
      :special-members:
   
       .. autoclasstoc::