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).
Is this a typical behaviour of the autosummary
directive? Is there any option to make it indeed go through the whole content?
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.