5

我正在使用 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"。一些谷歌搜索让我相信这个错误很“正常”？

4

3 回答 3

2

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

通常，您使用module指令或指令，而automodule不是两者。这也是您收到有关重复的警告的原因。不幸的是，据我所知，如果您正在使用，则无法在文档字符串中包含概要automodule

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

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

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

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

于 2013-01-17T16:05:03.770 回答
2

按照 Bonlenfum 的解决方案，这里有一个（甚至更）简洁的示例，它在模块索引和文档字符串中打印模块指令：

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

这与 Sphinx 1.2 配合得很好，并阅读了文档主题

于 2014-01-11T18:51:32.977 回答
2

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

概要选项应该由一个描述模块目的的句子组成——它目前仅用于全局模块索引。

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

"""

.. 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:声明结合起来，但显然这不是很容易维护。

于 2013-01-16T22:22:20.107 回答