Sphinx中重复使用automodule处理同一模块，如何无需:no-index:规避警告？

问题描述 #

我正在使用Sphinx为Python包中的某一模块编写文档，该模块包含module.function_a、module.function_b及更多函数与类。我希望拆分文档结构，在两个rst文件中分别使用automodule指令：

第一个rst文件内容：

.. automodule:: module
    :members:
    :exclude-members: function_b

第二个rst文件内容：

.. automodule:: module
    :members:
    :exclude-members: function_a

功能符合预期，但出现警告：

WARNING: duplicate object description of module, other instance in rst_file_1, use :no-index: for one of them.

请问是否存在无需使用:no-index:即可避免该警告的方法？或者有没有其他使用automodule将单个模块文档拆分为多页的方式？

解决方案 #

方法1：逐个指定成员，替换automodule #

直接放弃重复调用automodule，改为在每个文件中只提取需要展示的成员，从根源避免重复模块的警告：

• 第一个rst文件示例：

# 仅加载指定成员，而非整个模块
.. automodule:: module
    :members: function_a, ClassX
    # 列出所有要放在此页的函数/类

或者更精准地单独声明每个成员：

.. autofunction:: module.function_a
.. autoclass:: module.ClassX
# 添加其他需要放在该页的类或函数

• 第二个rst文件同理：

.. autofunction:: module.function_b
.. autoclass:: module.ClassY
# 添加其他需要放在该页的类或函数

方法2：用currentmodule简化成员引用 #

如果模块名称较长，可以先指定当前模块上下文，再简化成员写法：
第一个rst文件：

.. currentmodule:: module

.. autofunction:: function_a
.. autoclass:: ClassX

第二个rst文件：

.. currentmodule:: module

.. autofunction:: function_b
.. autoclass:: ClassY

补充：关于:no-index:的说明 #

如果一定要坚持用automodule拆分，:no-index:其实是官方认可的方案——它仅让其中一个模块实例不加入全局索引，不会影响文档内容展示，也不会产生其他副作用。但上面的两种方法更贴合拆分单模块文档到多页的需求，逻辑更清晰，也彻底规避了重复警告。

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