I want to use Sphinx's autosummary extension and templates to generate API docs recursively from docstrings. I want separate pages for each module, class, method, property and function. But it doesn't detect my templates at all. In fact, if I just remove the module.rst
file from _templates/autosummary/
, it renders the whole file exactly the same way as before. I've followed this SO question to the letter. If you're interested, the full repository is on GitHub.
Edit: It seems it does generate a different file, I had to delete docs/_autosummary for it to read the new template. However, now it generates a file with the sparse
header and description
header. It doesn't go into the {% if classes %}
and {% if functions %}
directives.
My directory structure is as follows:
Here are the relevant files so far:
index.rst
:
.. sparse documentation master file, created by
sphinx-quickstart on Fri Dec 29 20:58:03 2017.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to sparse's documentation!
==================================
.. toctree::
:maxdepth: 2
:caption: Contents:
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
modules.rst
:
API Reference
=============
Modules
-------
.. autosummary::
:toctree: _autosummary
sparse
_templates/autosummary/module.rst
:
{{ fullname | escape | underline }}
Description
-----------
.. automodule:: {{ fullname | escape }}
{% if classes %}
Classes
-------
.. autosummary:
:toctree: _autosummary
{% for class in classes %}
{{ class }}
{% endfor %}
{% endif %}
{% if functions %}
Functions
---------
.. autosummary:
:toctree: _autosummary
{% for function in functions %}
{{ function }}
{% endfor %}
{% endif %}
From Sphinx version 3.1 (June 2020), you can use the new :recursive:
option to get sphinx.ext.autosummary
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