:概要:不在Sphinx自动模块中工作

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:

我从狮身人面像那里得到了各种各样美妙的东西,所以对我来说一般都没有.我得到的唯一可疑的事情是:SEVERE: Duplicate ID: "module-CONF".一些谷歌搜索让我相信虽然这个错误很"正常"？

Answer 1

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

\n\n

\n

synopsis 选项应由一个句子组成，描述模块\xe2\x80\x99 的用途\xe2\x80\x93 它目前仅在全局模块索引中使用。

\n

\n\n

因此对于模块注释字符串：

\n\n

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

\n\n

概要出现在模块索引中——类似于

\n\n

\n

C

\n\n

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

\n

\n\n

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

\n\n

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

\n\n

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

\n\n

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

\n