python - :synopsis: not working in Sphinx automodule

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 option should consist of one sentence describing the module’s purpose – it is currently only used in the Global Module Index.

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

"""

.. 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) Configuration module, ....

或者，对于模块注释字符串(注意缩进):

"""

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

"""

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

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