python - 如何在 Sphinx 中避免 "SEVERE: Duplicate ID"警告我的 autodoc'd 模块？

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`.
'''

不会出现严重警告，概要中的消息将出现在模块索引中。

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