4.3. Going further with autosummary

To recap:

• we have a first draft for our API Reference, but it is messy;

• to improve it, we would like all the classes/functions of the library to have their own documentation pages;

• but we don’t want to create all the pages manually.

Fortunately, Sphinx extension autosummary can take care of this:

1. Activate the extension in your docs/conf.py:

extensions = [
    "sphinx_design",
    "sphinx_copybutton",
    "myst_parser",
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx.ext.intersphinx",
    "sphinx.ext.viewcode",
    "sphinx.ext.autosummary",
]

2. Define the template for your pages generated automatically. Here, we tell Sphinx to generate all the documentation pages on Python classes according to a specific template. Create a file in docs/_templates/autosummary/class.rst:

docs/_templates/autosummary/class.rst

{{ fullname }}
{{ underline }}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
    :members:

Note

We could also create a template for documentation of Python functions in docs/_templates/autosummary/function.rst.

3. Use the command .. autosummary:: in your docs/api/index.rst:

docs/api/index.rst

API Reference
=============

.. autosummary::
    :toctree: generated/
    :nosignatures:
    :template: autosummary/class.rst

    neuroplot.plot.single.SinglePlot
    neuroplot.plot.single.GIF
    neuroplot.plot.multiple.MultiplePlot
    neuroplot.transforms.Noise
    neuroplot.transforms.RescaleIntensity

4. Build your documentation!

Warning

autosummary will generate files in docs/api/generated. You don’t want to track these files. So create a docs/api/.gitignore file and put /generated inside.

Note

:nosignatures: is not essential here. You can try without and see what you prefer!

4.3.1. Improvements

With classes from both neuroplot.plot and neuroplot.transforms on the same page, I feel like we are mixing up apples and pears. Let’s rather build an autosummary for each module independently:

1. Create a docs/api/plot.rst file, dedicated to neuroplot.plot:

docs/api/plot.rst

``neuroplot.plot``: Plotting neuroimages
========================================

.. automodule:: neuroplot.plot

``neuroplot.plot.single``
-------------------------

.. automodule:: neuroplot.plot.single

.. currentmodule:: neuroplot.plot.single

.. autosummary::
    :toctree: generated/
    :nosignatures:
    :template: autosummary/class.rst

    SinglePlot
    GIF

``neuroplot.plot.multiple``
---------------------------

.. automodule:: neuroplot.plot.multiple

.. currentmodule:: neuroplot.plot.multiple

.. autosummary::
    :toctree: generated/
    :nosignatures:
    :template: autosummary/class.rst

    MultiplePlot

2. Create a docs/api/transforms.rst file, dedicated to neuroplot.transforms:

docs/api/transforms.rst

``neuroplot.transforms``: Transforming images before plotting
=============================================================

.. automodule:: neuroplot.transforms

.. currentmodule:: neuroplot.transforms

.. autosummary::
    :toctree: generated/
    :nosignatures:
    :template: autosummary/class.rst

    Noise
    RescaleIntensity

3. Change docs/api/index.rst to redirect to docs/api/plot.rst or docs/api/transforms.rst:

docs/api/transforms.rst

API Reference
=============

.. toctree::
    :maxdepth: 1

    plot
    transforms

4. Build the documentation!

That’s it! We have finished our API Reference, and therefore our documentation! It certainly doesn’t look complete, but this is only because we still have many docstrings to write. But I hope you got the idea!

Finally, now that our documentation is finished, we must deploy it so that it is publicly available.

---

If you don’t manage to run the tutorial

git reset --hard 9a105d76b8119b0f96bbaef15b52a6ebb711d03e