如何避免 Sphinx 中我的 autodoc'd 模块出现“严重：重复 ID”警告？答案

【问题标题】：How do I avoid "SEVERE: Duplicate ID" warnings for my autodoc'd modules in Sphinx?如何避免 Sphinx 中我的 autodoc'd 模块出现“严重：重复 ID”警告？
【发布时间】：2013-05-04 11:24:31
【问题描述】：

我正在使用 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 获取的源中添加概要选项。

【问题讨论】：

标签： python python-sphinx autodoc

【解决方案1】：

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

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

然后在你的源代码中你可以使用：

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

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

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

【讨论】：

【解决方案2】：

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

您可以尝试在模块标记中使用currentmodule 指令而不是module。似乎应该可以工作，虽然我承认我还没有真正尝试过。

【讨论】：

currentmodule 不接受 :synopsis: 选项，因此我需要将其移至 rST 文件，然后在源中包含任何 module 指令是多余的。我想知道我想要的是否是不可能的（目前）。 :/

【解决方案3】：

simno 所写的automodule:: 的:noindex: 有助于但阻止创建永久链接和交叉链接（例如:func:）将不起作用。将:noindex: 添加到module:: 时，一切正常，您不必使用currentmodule。

【讨论】：