如何使用Sphinx为导入的常量生成文档？

Sphinx autodoc的automodule默认不会文档化从其他模块导入到__init__.py的属性——正如官方文档所说，它只解析当前模块的源文件。针对你在rogue_scroll/__init__.py中导入的SCROLL_PROBS和SYLLABLES常量（原模块_scroll.py已写好文档字符串），这里有几个比你列出的方案更合理的解决办法：

优先方案：用automodule的:imported-members:选项 #

直接在你的rst文档里修改automodule指令，添加指定导入成员的参数：

.. automodule:: rogue_scroll
    :members:
    :imported-members: SCROLL_PROBS, SYLLABLES

如果需要文档化所有导入的成员，也可以直接写:imported-members:（不带参数），但建议明确指定成员，避免引入不必要的内容。

备选方案：在__init__.py中复用原文档字符串 #

不用手动复制文档，直接从原模块引用常量的__doc__属性，既保持代码简洁，又能让autodoc识别：

from . import _scroll
from ._scroll import Generator, Scroll, SYLLABLES, SCROLL_PROBS

# 复用原模块的文档字符串
SYLLABLES.__doc__ = _scroll.SYLLABLES.__doc__
SCROLL_PROBS.__doc__ = _scroll.SCROLL_PROBS.__doc__

__all__ = ("Scroll", "Generator", "SCROLL_PROBS", "SYLLABLES")

全局配置方案（谨慎使用） #

如果希望所有导入的成员都能被自动文档化，可以在Sphinx的conf.py中添加全局配置：

autodoc_default_options = {
    'members': True,
    'imported-members': True,
}

这种方式会影响所有模块，可能会引入不需要的文档内容，需根据项目情况选择。

对比你提到的三个方案 #

• 复制文档字符串：违反DRY原则，后续修改常量文档时需要同步更新两处，维护成本高
• 手动写rst文档：失去自动文档化的优势，每次修改常量都要同步更新rst，效率低
• 合并_scroll.py到__init__.py：虽然简单，但会让__init__.py过于臃肿，破坏模块拆分的设计逻辑

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