Sphinx autosummary仅生成类__init__方法，未生成其他公开方法

尝试使用Sphinx autosummary为mypackage/src/目录下的类生成文档，但Sphinx仅正确生成了类构造方法（init）的文档，类内的公开方法（如add_name）未生成对应的automethod指令。以下是项目相关信息：

项目结构 #

- docs/
    - build/
    - source/
       - _static/
       - generated/
           - mypackage.src.file_3.ClassInsideFile3.rst
       - api.rst
       - conf.py
       - index.rst
       - usage.rst
   - make.bat
   - Makefile
- mypackage/
   - __init__.py
   - file_1.py
   - file_2.py
   - src/
       - __init__.py
       - file_3.py
       - file_4.py
- tests/
- .gitignore
- poetry.lock
- pyproject.tomml
- README.md

docs/source/conf.py配置 #

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

import sys
import os


sys.path.insert(0, os.path.abspath('../..'))

project = 'mypackage'
copyright = '2023 My Name'
author = 'My Name'
release = '0.1.0'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

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

templates_path = ['_templates']
exclude_patterns = []

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

docs/source/api.rst内容 #

API
===

src
---
.. autosummary::
   :toctree: generated
   :recursive:
   
      mypackage.src.file_3.class_inside_file_3

mypackage/src/file_3.py代码 #

class ClassInsideFile3:
    "Docstring for the class"
    def __init__(self, names: list):
        """
        Initializes a ClassInsideFile3 object based on names argument
        
        :param names: A list of names
        :type names: list
        """
        self.names = names

    
    def add_name(self, name: str) -> None:
        """
        Appends a new name to the list of names if it does not already exist
        
        :param name: The name to be appended 
        :type name: str
        """
        if name not in self.names:
            self.names.append(name)

生成结果 #

执行sphinx-build docs/source docs/build后，生成的docs/source/generated/mypackage.src.file_3.ClassInsideFile3.rst内容如下：

mypackage.src.file_3.ClassInsideFile3
=====================================

.. currentmodule:: mypackage.src.file_3

.. autoclass:: ClassInsideFile3

   
   .. automethod:: __init__
   # Why isn't it creating an auto method for `add_name`?

   
   .. rubric:: Methods

   .. autosummary::
   
      ~ClassInsideFile3.__init__
      ~ClassInsideFile3.add_name

为何Sphinx不为add_name方法生成automethod指令？

问题源于Sphinx的默认行为配置，以下是具体修复方法：

1. 全局配置autodoc默认选项
   在conf.py的通用配置部分添加以下代码，让autoclass指令默认包含类的所有公开成员：

autodoc_default_options = {
    'members': True,
    'undoc-members': False,  # 可选：是否包含无文档字符串的成员
    'show-inheritance': True  # 可选：显示类的继承关系
}

2. 自定义autosummary模板（可选，确保自动生成带参数的指令）
   如果希望autosummary生成的类文档自动带上:members:选项，可通过自定义模板实现：

• 在docs/source/_templates目录下创建autosummary/class.rst文件（无此目录则新建）
• 写入以下内容：

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:
   :show-inheritance:

{% block methods %}
{% if methods %}
.. rubric:: {{ _('Methods') }}

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

{% block attributes %}
{% if attributes %}
.. rubric:: {{ _('Attributes') }}

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

3. 重新生成文档
   先清理旧的构建文件，再重新执行构建命令：

sphinx-build -b clean docs/source docs/build
sphinx-build docs/source docs/build

完成以上步骤后，add_name方法对应的automethod指令会被正确生成，方法文档也会正常显示。

内容的提问来源于stack exchange，提问作者Adventure-Knorrig