pythonpython-sphinxrestructuredtextautosummary

Sphinx's autosummary with recursive option is not being fully recursive


I am using Sphinx to document a Python project, which has the structure tree depicted below.

calculator
|   set_rho_and_f.py
|   set_rho_and_V_dot.py
|
├───data
│   ├───fans
│   │       ...
│   │
│   ├───functions
│   │       ...
│   │
│   └───systems
│           ...
|
├───docs
│   ├───build
|   |       ...
|   |
│   └───source
|           ...
|
├───results
|       ...
│
└───src
        fans.py
        functions.py
        systems.py

[Note: The coding project comprises set_rho_and_f.py and set_rho_anf_V_dot.py files, and data, results and src folders. The ellipses "..." represent content (directories and files) that has been herein omitted for the sake of compactness.]

I wanted to create a summary page using all docstrings in the project. In conf.py file I then added the autosummary extension:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary'
]
autosummary_generate = True

And in the reStructuredText file for the summary, I wrote

Summary
=======

.. autosummary::
   :toctree: _autosummary
   :recursive:

   data
   results
   src
   set_rho_and_f
   set_rho_and_V_dot

When getting an HTML file after doing make html, I experienced that even though autosummary can go through files inside a folder (just look at src section in the picture below) it cannot go through files inside subfolders of a folder (just look at data section in the picture below, which is missing data/fans, data/functions and data/systems sections).

enter image description here

Is this a typical behaviour of the autosummary directive? Is there any option to make it indeed go through the whole content?


Solution

  • Self-answering:

    After having a look at the Git Hub repository mentioned in James Leedham' answer for how to automatically document all content recursively with Sphinx, I found out that by adding an __init__.py file to the subdirectories, the respective content is included in the summary generated by autosummary (as shown in the picture below).

    It seems like that in this way autosummary interpreted the subdirectories as packages, which are then parsed as objects that may be documented under the autosummary scope.

    enter image description here