python - 使用 Sphinx 自动记录 Python

Question

这是先前关于 Sphinx的问题的通用版本。

有没有办法递归地自动记录包含类和函数的模块或包？

我认为为每个函数添加autofunctionor指令是愚蠢的；automodule必须有一种方法可以使该过程自动化，否则我根本看不到使用 Sphinx 的意义。

澄清： 而不是：

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. automethod:: Seg.method_1

        .. automethod:: Seg.method_2

        .. automethod:: Seg.method_3

        .......

        .. automethod:: Seg.method_n

这需要我手动剪切和粘贴所有方法名称并相应地更新文档，我想要一个类似的命令：

.. automodule:: segments.segments

    .. autoclass:: segments.segments.Seg

        .. MAGIC COMMAND: Automatically print the docstrings and signatures 
           of all Seg() methods.

score 37 · Accepted Answer

37

我们用

.. automodule:: module
   :members:

于 2009-08-25T13:26:39.013 回答

score 26 · Accepted Answer

为了使事情更容易，您可以使用此脚本（查看页面底部的最新版本）： http ://bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-script-to-sphinx

该脚本将解析您的包/模块并生成从文档字符串构建文档所需的所有其余文件。

我是这个脚本的原作者。

更新

该脚本现在作为apidoc成为 Sphinx 1.1 的一部分。

score 16 · Accepted Answer

Etienne 在他的回答中提到的脚本现在已作为 sphinx-apidoc 集成到 Sphinx 中。它完全符合 OP 的要求。它计划在 Sphinx 1.1 中发布，或者可以从 Hg repo 获得：

https://bitbucket.org/birkenfeld/sphinx

它对我来说效果很好。文档是这样写的：

> sphinx-apidoc --help
Usage: sphinx-apidoc-script.py [options] -o <output_path> <module_path>
           [exclude_paths, ...]

Look recursively in <module_path> for Python modules and packages and create
a reST file with automodule directives per package in the <output_path>.

score 0 · Accepted Answer

我认为为每个函数添加 autofunction 或 automodule 指令是愚蠢的；必须有一种方法可以使该过程自动化，否则我根本看不到使用 Sphinx 的意义。

我会建议Epydoc，它专门用于从文档字符串生成文档。

score -9 · Accepted Answer

您希望它比仅指定自动模块更简单吗？即使对于大型库，键入所有模块名称也需要 5 分钟的工作量。

这样做的原因是因为 Sphinx 几乎无法猜测需要记录的内容。

您还可以编写自动包，它将搜索模块并使用自动模块指令（如果自动模块还没有这样做）。

python - 使用 Sphinx 自动记录 Python

5 回答 5

Related

Reference