如何避免Sphinx中的autodoc'd模块出现"SEVERE:Duplicate ID"警告？

Question

我正在使用rST/Sphinx来记录我的Python,但是当构建它时会抛出警告,例如

...Code/doc/code.rst:3: SEVERE: Duplicate ID: "module-toast".

我的Python源文件记录如下:

#!/usr/bin/env python
'''
.. module:: toast
    :synopsis: Processes the blobs produced by :mod:`bread`.
'''
# my inline-rST documented code...

并且rST文件使用autodoc提供的automodule指令来拉出所有文档字符串并记录所有成员.

Toast
--------------------------------

.. automodule:: toast
    :members:

上面的组合似乎工作正常,但错误似乎意味着有一个正确的方法来做到这一点.如果我从源文件的顶部删除模块指令,则错误消失,但是我无法在Sphinx拾取的源中添加一个概要选项.

Answer 1

一种方法是使用:noindex:标志.

.. automodule:: toast
    :members:
    :noindex:

然后在您的源代码中,您可以使用:

#!/usr/bin/env python
'''
.. module:: toast
    :synopsis: Processes the blobs produced by :mod:`bread`.
'''

将不会有SEVERE警告,并且概要中的消息将出现在模块索引中.

另一方面,:noindex:如果模块.. module::在源文件中没有,则将模块从索引中隐藏.

Answer 2

我不确定，但我相信该指令会自行automodule创建一个指令。module然后，由于您已经指定了一个，因此有两个，因此您会收到重复的 ID 消息。

您可以尝试currentmodule在模块标记中使用指令而不是module. 看起来应该可行，尽管我承认我还没有真正尝试过。