使用Sphinx自动编写Python文档

这是a的一个广义版本

是否有一种方法可以递归地自动记录包含类和函数的模块或包

我认为为每个函数添加

autofunction

或

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.

---

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

之所以这样做，是因为斯芬克斯几乎猜不到需要记录的内容

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

我们使用

.. automodule:: module
   :members:

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

---

我建议您使用这个脚本，它专门用于从docstring生成文档。

为了让事情变得更简单，您可以使用这个脚本（查看页面底部的最新版本）：

此脚本将解析您的包/模块，并生成从docstring构建文档所需的所有rest文件

我是这个剧本的原作者

更新

---

这个脚本现在是斯芬克斯1.1 as的一部分。

艾蒂安在回答中提到的脚本，现在已经作为斯芬克斯apidoc集成到斯芬克斯中。这正是OP想要的。它将在Sphinx 1.1中发布，或可从Hg回购中获得：

这对我来说很好用。文件内容如下：

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

>斯芬克斯apidoc——帮助
用法：sphinx-apidoc-script.py[选项]-o
[排除路径，…]
递归查找Python模块和包并创建
中每个包都包含automodule指令的reST文件。

automodule会记录其中的类和功能吗？它不会在这里这样做。它会的，你只需要更仔细地阅读斯芬克斯的文档。所有指令都接受特殊参数，以使其按您的要求运行。请详细说明或链接好吗？手动执行的问题不是执行的工作，尽管这很不方便且重复。这是因为它容易出错。您可能会错过一些东西，并且无论何时更改源的结构，结果都将过时。太棒了！知道如何告诉Sphinx显示所有成员，而不仅仅是那些有docstring的成员吗？你能帮我找到这件事的消息来源吗？谢谢所有内容都写在这里：Inshort:add:undoc members:如何在不将样式块着色为

块的情况下包含样式块（如上面的命令帮助输出片段）？Epydoc似乎已经死了。与最新的docutils版本不兼容几乎是一个阻碍。