自动生成所有Python包内容的文档
我正在尝试使用Sphinx为我的代码库自动生成基本文档。 然而，我很难指示狮身人面像recursion扫描我的文件。
我有一个像下面这样的文件夹结构的Python代码库：
<workspace> src mypackage __init__.py subpackageA __init__.py submoduleA1 submoduleA2 subpackageB __init__.py submoduleB1 submoduleB2 我在<workspace>运行了sphinx-quickstart，所以现在我的结构如下所示：
<workspace> src mypackage __init__.py subpackageA __init__.py submoduleA1 submoduleA2 subpackageB __init__.py submoduleB1 submoduleB2 index.rst _build _static _templates
我已经阅读了快速入门教程http://sphinx.pocoo.org/tutorial.html ，虽然我仍然试图理解文档，但是它的措辞让我担心Sphinx假设我将手动创build我的代码库中的每个模块/类/function的文档文件。
但是，我注意到了“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:
我有几十个在子包中定义的类和函数。 然而，当我运行：
sphinx-build -b html . ./_build
它报告：
updating environment: 1 added, 0 changed, 0 removed
这似乎没有导入任何东西在我的包里面。 查看生成的index.html在“Contents：”旁边没有显示任何内容。 索引页只显示“mypackage（模块）”，但点击它显示它也没有内容。
你如何指导Sphinxrecursion地parsing一个包，并自动生成所遇到的每个类/方法/函数的文档，而不必自己手动列出每个类？
也许apigen.py可以帮助： https ： //github.com/nipy/nipy/tree/master/tools 。
这个工具在这里很简短地描述： http : //comments.gmane.org/gmane.comp.python.sphinx.devel/2912 。
更新： 狮身人面像版本1.1中添加了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>.
您可以将sphinx-apidoc与sphinx-quickstart混合，以创build如下所示的整个doc项目：
$ sphinx-apidoc -F -o docs project
这个调用将使用sphinx-quickstart生成一个完整的项目，并在Python项目中recursion地查找Python模块。
希望这可以帮助！
注意
对于Sphinx（实际上是执行Sphinx的Python解释器）来查找你的模块，它必须是可导入的。 这意味着模块或包必须位于sys.path中的某个目录中 – 相应地在configuration文件中修改sys.path
所以，去你的conf.py并添加
import an_example_pypi_project.useful_1 import an_example_pypi_project.useful_2
现在你的index.rst看起来像：
.. toctree:: :glob: example an_example_pypi_project/*
和
make html
