python-Sphinx自动摘要生成的文档缺少所有dunder方法，除了__init__`

Question

我正在使用Sphinx的自动摘要为模块的每个成员自动生成单独的rst文件。该文档按预期方式创建，除了生成的rst文件缺少__init__之外的所有dunder方法。

在我的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

在我的主要rst文件中，按如下所示设置自动摘要：

.. autosummary::
    :toctree: my_module_members

    my_module.MyClassA
    my_module.MyClassB

按预期，自动摘要会创建一个名为/my_module_members的子目录，其中为模块的每个成员创建了单独的rst文件。但是，在这些自动生成的第一个文件的“方法”部分中仅列出了__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

问题出在自动摘要用于类的默认模板上。这是文档中的relevant page，但直接查看默认模板会更有用：

# 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__行；也许我们有不同版本的狮身人面像）。重要的部分是{% for item in methods %}循环。上面链接的文档简要提到methods仅包括“公共”方法，这意味着方法不是以下划线开头。根据__init__()的第242行，sphinx/ext/autosummary/generate.py也被视为公开的，尽管似乎没有任何地方对此进行记录。因此希望可以解释您所看到的行为。

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

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

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

3. 尝试使用autoclasstoc。全面披露：这是我写的一个程序包，旨在更好地总结sphinx文档中的类方法。它比自动摘要更具可配置性，并且默认情况下它包括所有方法。它还会折叠继承的方法，这对于大型类而言可能确实不错，尽管可能与您无关，也可能不相关。

   This page描述了如何结合使用autoclasstoc和autosummary，但要点是您需要一个看起来像这样的自定义模板：

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