Sphinx-autodoc不识别conf.py默认配置，Pandas数据框文档冗余问题

1. conf.py配置不生效：sphinx-apidoc生成的rst文件中明确指定了:undoc-members:，该选项优先级高于conf.py中的autodoc_default_options，导致默认配置被覆盖。
2. exclude-members格式错误：多成员需用逗号分隔的字符串（允许空格），而非列表或其他格式。
3. 源码注释未被识别：类变量的注释写法可能不符合Sphinx识别规则，且变量在类定义时直接执行CSV读取操作，导致Sphinx生成文档时会执行该代码并输出完整DataFrame内容。

方案一：修改sphinx-apidoc生成参数 #

执行sphinx-apidoc时添加--no-undoc-members参数，让生成的rst默认禁用未文档化成员的输出：

sphinx-apidoc --module-first -f --no-undoc-members -o source/ ../src

同时在source/conf.py中正确配置需要排除的成员：

autodoc_default_options = {
    'exclude-members': 'form, form_long'
}

此配置下，后续执行sphinx-apidoc不会覆盖自定义规则，conf.py的设置会生效。

方案二：自定义sphinx-apidoc模板（永久生效） #

如果需要长期固定生成规则，可修改sphinx-apidoc的模板：

1. 找到Sphinx的apidoc模板目录（通常在lib/pythonX.X/site-packages/sphinx/templates/apidoc，根据Python版本调整）。
2. 复制module.rst_tmpl到项目的source/_templates/apidoc目录（无则创建）。
3. 修改模板中的automodule块为自定义配置：

.. automodule:: {{ fullname }}
   :members:
   :no-undoc-members:
   :show-inheritance:
   :exclude-members: form, form_long

此后每次执行sphinx-apidoc都会生成带有该配置的rst文件，不会被覆盖。

方案三：让类变量注释被Sphinx正确识别 #

如果希望保留未文档化成员但排除特定变量，可在源码中为类变量添加Sphinx兼容的注释，使其不再被视为未文档化成员：

import pandas as pd

class MyApp:
    #: 存储表单数据的DataFrame
    form = pd.read_csv('form.csv')
    
    #: 存储长格式表单数据的DataFrame
    form_long = pd.read_csv('form_long.csv')

#: 是Sphinx官方认可的类变量注释格式，需直接放在变量定义上方。添加注释后，这些变量会被:members:包含，不会输出完整DataFrame内容。

额外技巧：阻止Sphinx执行CSV读取代码 #

若不想在生成文档时执行类变量的CSV读取操作，可通过环境变量判断：

import pandas as pd
import os

class MyApp:
    if not os.environ.get('SPHINX_BUILD'):
        form = pd.read_csv('form.csv')
        form_long = pd.read_csv('form_long.csv')
    else:
        form = None
        form_long = None
    #: 存储表单数据的DataFrame
    #: 存储长格式表单数据的DataFrame

执行文档生成前设置环境变量：

export SPHINX_BUILD=1 && make html

这样Sphinx生成文档时不会读取CSV，也就不会输出完整表格。

内容的提问来源于stack exchange，提问作者pauljohn32