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。似乎应该工作，但我承认我还没有真正尝试过。

Answer 3

simno撰写的:noindex: automodule::有助于阻止创建永久链接和交叉链接（例如:func:）。将:noindex:添加到module::时，一切都按预期进行，您不必使用currentmodule。