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

Answer 1

我们用

.. automodule:: module
   :members:

Answer 2

为了方便起见,您可以使用此脚本(请查看最新版本的页面底部):http: //bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-script-to-sphinx

此脚本将解析您的包/模块,并生成从docstrings构建doc所需的所有其余文件.

我是这个脚本的原作者.

UPDATE

此脚本现在是apidoc的Sphinx 1.1的一部分.

Answer 3

在他的回答中提到的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>.