python - 如何避免 Sphinx 中我的 autodoc 模块出现“严重：重复 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 获取的源中添加概要选项。

score 7 · Accepted Answer

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

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

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

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

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

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

score 4 · Accepted Answer

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

您可以尝试currentmodule在模块标记中使用该指令而不是module. 似乎这应该可行，尽管我承认我实际上还没有尝试过。

score 0 · Accepted Answer

由 simno 编写的 for 有助于但防止创建永久链接和交叉链接（例如）:noindex:将不起作用。当添加到一切按预期工作时，您不必使用.automodule:::func::noindex:module::currentmodule

3 回答 3