自动生成所有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