如何在Sphinx文档中显示私有成员常量的实际值？

我之前也碰到过一模一样的情况，问题根源在于Python的**名称修饰（name mangling）**机制和Sphinx autodoc的默认行为冲突：双下划线开头的类属性会被Python自动重命名（比如你的__MY_TEST_CONSTANT会被改成_Test__MY_TEST_CONSTANT），而Sphinx的autodoc在扫描时找不到原始的__MY_TEST_CONSTANT属性，只能默认显示None。

下面给你几个可行的解决方案，按推荐程度排序：

方案1：改用单下划线前缀（最简便） #

如果你的常量只是想标记为内部使用，不需要严格的名称修饰，把双下划线改成单下划线就搞定了。这样既保留了“私有”的语义，又能让autodoc正确识别并提取属性值：

class Test:
    """My Test Class"""
    _MY_TEST_CONSTANT = 98.2
    """My test constant docu"""

重新生成文档后，就能看到常量值正确显示为98.2了。

方案2：手动指定修饰后的属性值（适合必须保留双下划线的场景） #

如果一定要用双下划线前缀，可以在你的.rst文档中手动补充属性的实际值。因为Python已经把__MY_TEST_CONSTANT重命名为_Test__MY_TEST_CONSTANT，你可以用autodata指令来修正显示：

.. automodule:: mymodule
    :members:
    :private-members:

.. autodata:: mymodule.Test._Test__MY_TEST_CONSTANT
    :annotation: = 98.2

不过这种方式需要手动维护值，当常量值变化时要同步更新文档，适合常量不常修改的场景。

方案3：自定义autodoc处理器（自动适配名称修饰） #

如果你有很多双下划线前缀的常量，不想手动一个个维护，可以在Sphinx的conf.py中添加一个自定义处理器，自动识别并替换正确的属性值：

def fix_private_attr_value(app, obj, membername, options, lines):
    # 处理双下划线开头的非特殊方法/属性
    if membername.startswith('__') and not membername.endswith('__'):
        # 生成Python修饰后的属性名
        mangled_name = f"_{obj.__name__}{membername}"
        if hasattr(obj, mangled_name):
            actual_value = getattr(obj, mangled_name)
            # 找到显示"= None"的行并替换
            for idx, line in enumerate(lines):
                if f"{membername} = None" in line:
                    lines[idx] = f"{membername} = {actual_value}"

def setup(app):
    app.connect('autodoc-process-docstring', fix_private_attr_value)

这个函数会在autodoc处理类属性的docstring时，自动查找修饰后的属性名，获取实际值并替换文档中的None，一劳永逸解决批量私有常量的显示问题。

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