使用 Sphinx 自动记录 Python
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/1328041/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Autodocumenting Python using Sphinx
提问by Adam Matan
This is a generalized version of a previous question regarding Sphinx.
这是之前关于 Sphinx 的问题的概括版本。
Is there a way to recursively autodocument modules or packages which contain classes and functions within them?
有没有办法递归地自动记录包含类和函数的模块或包？
I think it is silly to add the autofunctionor automoduledirective for each function; There must be a way to automate the process, otherwise I don't see the point of using Sphinx at all.
我认为为每个函数添加autofunctionorautomodule指令是愚蠢的；必须有一种方法可以使该过程自动化，否则我根本看不到使用 Sphinx 的意义。
Clarification:Instead of :
澄清：而不是：
.. automodule:: segments.segments
.. autoclass:: segments.segments.Seg
.. automethod:: Seg.method_1
.. automethod:: Seg.method_2
.. automethod:: Seg.method_3
.......
.. automethod:: Seg.method_n
Which requires me to manually cut-and-paste all method names and update the documentation correspondingly, I want to have a command like:
这需要我手动剪切和粘贴所有方法名称并相应地更新文档，我想要一个命令，如：
.. automodule:: segments.segments
.. autoclass:: segments.segments.Seg
.. MAGIC COMMAND: Automatically print the docstrings and signatures
of all Seg() methods.
回答by S.Lott
We use
我们用
.. automodule:: module
:members:
回答by Etienne
To make things easier you can use this script (look at the bottom of the page for the last version): http://bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-script-to-sphinx
为了让事情更容易，你可以使用这个脚本（查看页面底部的最新版本）：http: //bitbucket.org/birkenfeld/sphinx/issue/98/add-the-autogenerate-script-to-sphinx
This script will parse your packages/modules and generate all the rest files necessary to build the doc from docstrings.
该脚本将解析您的包/模块并生成从文档字符串构建文档所需的所有其余文件。
I'm the original author of this script.
我是这个脚本的原作者。
UPDATE
更新
This script is now part of Sphinx 1.1 as apidoc.
回答by Jonathan Hartley
Etienne's script, mentioned in his answer, has now been integrated into Sphinx as sphinx-apidoc. It does exactly what the OP wants. It is slated for release in Sphinx 1.1, or is available from the Hg repo:
在他的回答中提到的 Etienne 的脚本现在已作为 sphinx-apidoc 集成到 Sphinx 中。它完全符合 OP 的要求。它计划在 Sphinx 1.1 中发布，或者可以从 Hg 仓库获得：
https://bitbucket.org/birkenfeld/sphinx
https://bitbucket.org/birkenfeld/sphinx
It works beautifully for me. The docs read thus:
它对我来说效果很好。文档是这样读的：
> 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>.
回答by Bastien Léonard
I think it is silly to add the autofunction or automodule directive for each function; There must be a way to automate the process, otherwise I don't see the point of using Sphinx at all.
我认为为每个函数添加 autofunction 或 automodule 指令是愚蠢的；必须有一种方法可以使该过程自动化，否则我根本看不到使用 Sphinx 的意义。
I would suggest Epydoc, which is specialized at generating documentation from docstrings.
我建议Epydoc，它专门用于从文档字符串生成文档。
回答by iElectric
You want it more simpler than just specifing automodule? Even for a large library, it's 5min amount of work to type all the module names.
您希望它比仅指定 automodule 更简单吗？即使对于大型库，键入所有模块名称也需要 5 分钟的工作量。
The reason of doing so is because Sphinx hardly guesses what needs to be documented.
这样做的原因是因为 Sphinx 很难猜测需要记录的内容。
You could also write autopackage, that would search for modules and use automodule directive (if automodule does not do that already).
您也可以编写 autopackage，它会搜索模块并使用 automodule 指令（如果 automodule 还没有这样做）。
