：概要：在狮身人面像自动模块中不起作用

Question

我正在使用 Sphinx，非常喜欢它，但它不会获取模块概要。没有错误或任何东西，只是简单......什么都没有。这是我要自动记录的模块：

# vim: set fileencoding=utf-8 :
"""
.. module:: CONF
   :synopsis: Configuration module, tells where data files are.

.. moduleauthor:: Mr Anderson <mr@matrix.com>
"""

这是 ReST 索引文件中的 Sphinx 指令：

.. automodule:: CONF
   :synopsis:

我从 Sphinx 那里得到了各种其他美妙的东西，所以它对我来说通常不会坏掉。我得到的唯一可疑的东西是：SEVERE: Duplicate ID: "module-CONF"。一些谷歌搜索让我相信这个错误很“正常”？

Answer 1

不确定这是否真的回答了您的问题，但也许您正在“错误”的地方寻找概要。 （'错误'，因为期望它出现在您的 automodule 指令所在的位置似乎很合理）。来自module markup 上的文档（强调我的）：

synopsis 选项应该包含一个描述模块用途的句子——它目前仅用于全局模块索引。

所以对于模块注释字符串：

"""

.. module:: CONF
  :synopsis: Configuration module, tells where data files are.
    continuation possible here... (though goes against the point of synopses...)
  :platform: Windows

"""

大纲出现在模块索引中——类似于

c

CONF (Windows) 配置模块，....

或者，对于模块注释字符串（注意缩进）：

"""

:synopsis: Configuration module, tells where data files are to.

"""

将在您放入automodule:: 指令的位置呈现，但在模块索引中不会。对我来说，样式是在成员函数中呈现参数。

作为一种有点讨厌的解决方法，您可以将这两个 :synopsis: 声明结合起来，但显然这不是很容易维护。

Answer 2

我认为您在 automodule 指令上错误地使用了 :synopsis: 选项。在automodule 上使用此选项的方式与在module 上使用的方式相同。换句话说，您必须在任一指令的 :synopsis: 选项中指定内联概要。

通常，您使用module 指令或 automodule 指令，不能同时使用。这也是您收到有关重复的警告的原因。不幸的是，据我所知，如果您使用automodule

，则无法在文档字符串中包含概要

所以如果你想在没有收到警告的情况下使用自动模块和概要，我认为你必须这样做：

.. automodule:: CONF
   :synopsis: Configuration module, tells where data files are.

然后去掉 src 文件本身中的`.. module:: 指令。

我认为您拥有它的方式会起作用，但您会收到该警告。此外，您应该从automodule 中删除:synopsis: 选项：后面没有实际的概要字符串，这对您没有任何好处，并且可能导致“空”概要。

Answer 3

按照 Bonlenfum 的解决方案，这里有一个（甚至更）简洁的示例，它在模块索引和文档字符串中打印模块指令：

"""
.. module:: CONF
  :synopsis: written in module index..................................newlines are
    automatically handled (still, mind the spacing)
  :platform: Windows

.. moduleauthor:: Mr Anderson <mr@matrix.com>

:synopsis: this is written in the docstrings..........................newlines are handled
  automatically handled (mind spacing) or I can force newlines with \n
  a newline character.
"""

我添加了“...”来添加空格，这样该行的长度足以让 sphinx 自动在换行符上继续。模块作者仅显示在文档字符串中（不是索引）。

这与 Sphinx 1.2 和 read the docs 主题配合得很好