自动为所有 Python 包内容生成文档
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/4616693/
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
Automatically Generating Documentation for All Python Package Contents
提问by Cerin
I'm trying to auto-generate basic documentation for my codebase using Sphinx. However, I'm having difficulty instructing Sphinx to recursively scan my files.
我正在尝试使用 Sphinx 为我的代码库自动生成基本文档。但是，我很难指示 Sphinx 递归扫描我的文件。
I have a Python codebase with a folder structure like:
我有一个 Python 代码库，其文件夹结构如下：
<workspace>
src
mypackage
__init__.py
subpackageA
__init__.py
submoduleA1
submoduleA2
subpackageB
__init__.py
submoduleB1
submoduleB2
I ran sphinx-quickstart in <workspace>, so now my structure looks like:
我在 中运行了 sphinx-quickstart <workspace>，所以现在我的结构看起来像：
<workspace>
src
mypackage
__init__.py
subpackageA
__init__.py
submoduleA1
submoduleA2
subpackageB
__init__.py
submoduleB1
submoduleB2
index.rst
_build
_static
_templates
I've read the quickstart tutorial, and although I'm still trying to understand the docs, the way it's worded makes me concerned that Sphinx assumes I'm going to manually create documentation files for every single module/class/function in my codebase.
我已经阅读了快速入门教程，虽然我仍在尝试理解文档，但它的措辞方式让我担心 Sphinx 假设我将为代码库中的每个模块/类/函数手动创建文档文件.
However, I did notice the "automodule" statement, and I enabled autodoc during quickstart, so I'm hoping most of the documentation can be automatically generated. I modified my conf.py to add my src folder to sys.path and then modified my index.rst to use automodule. So now my index.rst looks like:
但是，我确实注意到了“automodule”语句，并且在快速入门期间启用了 autodoc，因此我希望大多数文档都可以自动生成。我修改了我的 conf.py 以将我的 src 文件夹添加到 sys.path，然后修改我的 index.rst 以使用 automodule。所以现在我的 index.rst 看起来像：
Contents:
.. toctree::
:maxdepth: 2
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
.. automodule:: alphabuyer
:members:
I have dozens of classes and functions defined in the subpackages. Yet, when I run:
我在子包中定义了几十个类和函数。然而，当我运行时：
sphinx-build -b html . ./_build
it reports:
它报告：
updating environment: 1 added, 0 changed, 0 removed
And this appears to have failed to import anything inside my package. Viewing the generated index.html shows nothing next to "Contents:". The Index page only shows "mypackage (module)", but clicking it shows it also has no contents.
这似乎未能在我的包中导入任何内容。查看生成的 index.html 在“Contents:”旁边没有显示任何内容。索引页面只显示“mypackage (module)”，但点击它显示它也没有内容。
How do you direct Sphinx to recursively parse a package and automatically generate documentation for every class/method/function it encounters, without having to manually list every class yourself?
你如何指导 Sphinx 递归解析一个包并为它遇到的每个类/方法/函数自动生成文档，而不必自己手动列出每个类？
采纳答案by mzjn
Perhaps apigen.py can help: https://github.com/nipy/nipy/tree/master/tools.
也许 apigen.py 可以提供帮助：https: //github.com/nipy/nipy/tree/master/tools。
This tool is described very briefly here: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.
这个工具在这里非常简要地描述：http: //comments.gmane.org/gmane.comp.python.sphinx.devel/2912。
Or better yet, use pdoc.
或者更好的是，使用pdoc。
Update: the sphinx-apidocutility was added in Sphinx version 1.1.
更新：在 Sphinx版本 1.1 中添加了sphinx-apidoc实用程序。
回答by Daniel
You can try using sphinx-apidoc.
您可以尝试使用 sphinx-apidoc。
$ sphinx-apidoc --help
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_paths, ...]
Look recursively in <module_path> for Python modules and packages and create
one reST file with automodule directives per package in the <output_path>.
You can mix sphinx-apidoc with sphinx-quickstart in order to create the whole doc project like this:
您可以将 sphinx-apidoc 与 sphinx-quickstart 混合使用，以便像这样创建整个 doc 项目：
$ sphinx-apidoc -F -o docs project
This call will generate a full project with sphinx-quickstart and Look recursively in (project) for Python modules.
此调用将生成一个带有 sphinx-quickstart 的完整项目，并在（项目）中递归查找 Python 模块。
Hope this helps!
希望这可以帮助！
回答by macm
Note
笔记
For Sphinx (actually, the Python interpreter that executes Sphinx) to find your module, it must be importable. That means that the module or the package must be in one of the directories on sys.path – adapt your sys.path in the configuration fileaccordingly
为了让 Sphinx（实际上是执行 Sphinx 的 Python 解释器）找到您的模块，它必须是可导入的。这意味着，该模块或包装必须在sys.path中的目录之一-适应您的sys.path中的配置文件中的相应
So, go to your conf.py and add
因此，转到您的 conf.py 并添加
import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2
Now your index.rst looks like:
现在你的 index.rst 看起来像：
.. toctree::
:glob:
example
an_example_pypi_project/*
and
和
make html
make html
