我正在使用 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"
。一些谷歌搜索让我相信这个错误是相当“正常的”?
最佳答案
不确定这是否真的回答了您的问题,但也许您正在寻找“错误”的地方来获取提要。 ('错误',因为期望它出现在您的 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:
声明结合起来,但显然这不是很容易维护。
关于python - :synopsis: not working in Sphinx automodule,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/14361140/