Automatically generate documentation for all components of the Python package

Question

I am trying to automatically generate basic documentation for my codebase using Sphinx. However, I am having difficulty with the Sphinx instruction to recursively scan my files.

I have a Python code base with a folder structure like:

<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 this:

 <workspace> src mypackage __init__.py subpackageA __init__.py submoduleA1 submoduleA2 subpackageB __init__.py submoduleB1 submoduleB2 index.rst _build _static _templates 

I read the quickstart tutorial http://sphinx.pocoo.org/tutorial.html , and although I am still trying to understand the documents, the way it formulated makes me worry about what Sphinx suggests I am going to manually create documentation files for each separate module / class / function in my codebase.

However, I noticed the automodule statement, and I turned on autodoc during quick start, so I hope that most of the documentation can be generated automatically. I changed 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 this:

 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 subpackages. However, when I run:

 sphinx-build -b html . ./_build 

he reports:

 updating environment: 1 added, 0 changed, 0 removed 

And this, it seems, failed to import anything inside my package. Viewing the generated index.html shows nothing next to "Content:". On the Index page, only “mypackage (module)” is displayed, but clicking on it shows that it also contains no content.

How do you direct Sphinx to recursively parse a package and automatically generate documentation for each class / method / function that it comes across without having to manually list each class manually?

Answer 1

Perhaps apigen.py can help: https://github.com/nipy/nipy/tree/master/tools .

This tool is very briefly described here: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912 .

Or better yet, use pdoc .

---

Update: The sphinx-apidoc utility was added in Sphinx version 1.1 .

Answer 2

You can try using 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 to create an entire document project as follows:

 $ sphinx-apidoc -F -o docs project 

This call will generate a complete project using sphinx-quickstart and search recursively in (project) for Python modules.

Hope this helps!

Answer 3

Note

For Sphinx (in fact, the Python interpreter that runs Sphinx) to find your module, it must be imported. Which means that the module or package must be in one of the directories on sys.path - adapt your sys.path in the configuration file accordingly

So go to your conf.py and add

 import an_example_pypi_project.useful_1 import an_example_pypi_project.useful_2 

Now your index.rst looks like this:

 .. toctree:: :glob: example an_example_pypi_project/* 

and

make html