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指令所在的位置似乎很合理）。来自module markup的文件（强调我的）：

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

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

"""

.. 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

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

通常，您使用module指令或 automodule指令，而不是两者。这也是您收到重复警告的原因。这很不幸，因为据我所知，如果您使用automodule

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

因此，如果您想在不收到警告的情况下使用自动模块和概要，我认为您必须这样做：

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

然后摆脱src文件本身的`.. module::指令。

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

Answer 3

遵循Bonlenfum的解决方案，这是一个（甚至更多）简洁的示例，它在模块索引和doc字符串中打印模块指令：

"""
.. 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能够自动在换行符上继续。模块作者仅显示在doc字符串中（而不是索引）。

这适用于Sphinx 1.2和read the docs主题

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

3 个答案:

C