如何在Sphinx自动文档中隐藏属性但保留其在文档字符串中的显示

方案一：手动指定排除属性（适合少量属性场景） #

直接在Sphinx的rst文档中给autoclass指令添加:exclude-members:参数，列出需要隐藏的属性即可：

.. autoclass:: your_module.TestClass
    :exclude-members: attr1, attr2, attr3

优点是简单直接，缺点是属性较多时手动维护麻烦。

方案二：自定义Sphinx扩展自动过滤属性（自动化首选） #

写一个轻量的Sphinx扩展，自动识别并隐藏类的非可调用属性（即变量属性，排除方法）：

1. 在你的Sphinx项目目录下创建sphinx_ext/hide_attributes.py文件，内容如下：

from sphinx.ext.autodoc import ClassDocumenter

def setup(app):
    def skip_attributes(app, what, name, obj, skip, options):
        # 仅处理类成员，且判断是否为非可调用属性
        if what == 'class' and not callable(obj):
            return True  # 返回True表示跳过该成员，不生成文档
        return skip

    app.connect('autodoc-skip-member', skip_attributes)
    return {'version': '0.1', 'parallel_read_safe': True}

2. 在Sphinx配置文件conf.py中启用该扩展：

extensions = [
    # 保留你原本的其他扩展，比如sphinx.ext.autodoc等
    'sphinx_ext.hide_attributes'
]

配置完成后，使用.. autoclass::生成文档时，所有类属性会被自动隐藏，而Jupyter Notebook中Shift+Tab+Tab仍能正常查看文档字符串里的属性列表。

方案三：用特殊标记分隔Jupyter专属内容（灵活可控） #

在类的文档字符串中用自定义标记包裹属性列表，再通过Sphinx的文档字符串预处理功能移除这部分内容：

1. 类的文档字符串写法示例：

class TestClass:
    """这是测试类的核心功能说明。

    .. jupyter-only::
        属性列表：
        - attr1: 用于存储基础配置的属性
        - attr2: 记录运行状态的属性
    """
    attr1 = 1
    attr2 = 2

2. 在conf.py中添加文档字符串预处理函数：

def setup(app):
    def process_docstring(app, what, name, obj, options, lines):
        in_jupyter_block = False
        new_lines = []
        for line in lines:
            if '.. jupyter-only::' in line:
                in_jupyter_block = True
                continue
            if in_jupyter_block:
                # 假设属性列表后以空行结束，遇到空行则退出隐藏块
                if line.strip() == '':
                    in_jupyter_block = False
                continue
            new_lines.append(line)
        lines[:] = new_lines

    app.connect('autodoc-process-docstring', process_docstring)
    return {'version': '0.1', 'parallel_read_safe': True}

这种方法可以精准控制哪些内容仅在Jupyter中显示，Sphinx生成文档时会自动剔除标记包裹的部分。

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