：概要：不在斯芬克斯automodu中工作

Question

我用的是狮身人面像，真的很喜欢，但它不会拿起模块的大纲。没有错误什么的，只是简单的。。。没有什么。这是我试图自动记录的模块：

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

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

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

^{pr2}$

我从狮身人面像那里得到了其他各种各样奇妙的东西，所以它对我来说并不坏。我唯一怀疑的是：SEVERE: Duplicate ID: "module-CONF"。一些谷歌搜索让我相信这个错误很“正常”？在

Answer 1

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

通常，您可以使用module指令或指令automodule，而不是两者都使用。这也是为什么你会收到关于重复的警告。这很不幸，因为据我所知，如果使用automodule，就没有办法在docstring中包含概要

因此，如果您想在没有收到警告的情况下使用automodule和synopsis，我认为您必须这样做：

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

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

我想你的方法会奏效，但你会得到警告的。另外，您应该从automodule中删除:synopsis:选项：如果后面没有实际的概要字符串，它对您没有任何好处，并且可能导致出现“空”的概要。在

Answer 2

在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字符串（而不是索引）中。在

这与sphinx1.2和read the docs主题配合得很好

Answer 3

不确定这是否真的回答了你的问题，但也许你找错了地方，没有找到大纲。（'wrong'，因为它似乎相当合理地期望它出现在您的automodule指令所在的位置）。从module markup（emphasis mine）的文档中：

^{bq}$

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

"""

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

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

^{pr2}$

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

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