CODEWITHSUNDEEP
pythonpython-sphinxdocumentation-generationsphinx-apidoc
Cerin
Cerin

Reputation: 64880

Automatically Generating Documentation for All Python Package Contents

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.

I have a Python codebase 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:

<workspace>
├── src
│   └── mypackage
│       ├── __init__.py
│       │
│       ├── subpackageA
│       │   ├── __init__.py
│       │   ├── submoduleA1
│       │   └── submoduleA2
│       │
│       └── subpackageB
│           ├── __init__.py
│           ├── submoduleB1
│           └── ubmoduleB2
│
├── 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.

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:

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.

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?

Upvotes: 57

Views: 31238

Answers (4)

Daniel
Daniel

Reputation: 754

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 in order to create the whole doc project like this:

$ sphinx-apidoc -F -o docs project

This call will generate a full project with sphinx-quickstart and Look recursively in <module_path> (project) for Python modules.

Upvotes: 61

James Leedham
James Leedham

Reputation: 2404

From Sphinx version 3.1 (June 2020), if you're happy to use sphinx.ext.autosummary to display summary tables, you can use the new :recursive: option to automatically detect every module in your package, however deeply nested, and automatically generate documentation for every attribute, class, function and exception in that module.

See my answer here: https://stackoverflow.com/a/62613202/12014259

Upvotes: 3

mzjn
mzjn

Reputation: 51052

Perhaps apigen.py can help: 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.

Or better yet, use pdoc.

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

Upvotes: 18

macm
macm

Reputation: 2019

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

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

and

make html

Upvotes: 6

Related Questions