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 %}
I ended up needing the following files:
modules.rst
:
API Reference
=============
.. rubric:: Modules
.. autosummary::
:toctree: generated
sparse
_templates/autosummary/module.rst
:
{{ fullname | escape | underline }}
.. rubric:: Description
.. automodule:: {{ fullname }}
.. currentmodule:: {{ fullname }}
{% if classes %}
.. rubric:: Classes
.. autosummary::
:toctree: .
{% for class in classes %}
{{ class }}
{% endfor %}
{% endif %}
{% if functions %}
.. rubric:: Functions
.. autosummary::
:toctree: .
{% for function in functions %}
{{ function }}
{% endfor %}
{% endif %}
_templates/autosummary/class.rst
:
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. autoclass:: {{ objname }}
{% block methods %}
{% block attributes %}
{% if attributes %}
.. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
.. autosummary::
:toctree:
{% for item in all_attributes %}
{%- if not item.startswith('_') %}
{{ name }}.{{ item }}
{%- endif -%}
{%- endfor %}
{% endif %}
{% endblock %}
{% if methods %}
.. HACK -- the point here is that we don't want this to appear in the output, but the autosummary should still generate the pages.
.. autosummary::
:toctree:
{% for item in all_methods %}
{%- if not item.startswith('_') or item in ['__call__'] %}
{{ name }}.{{ item }}
{%- endif -%}
{%- endfor %}
{% endif %}
{% endblock %}
_templates/autosummary/base.rst
:
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}
.. auto{{ objtype }}:: {{ objname }}
I also needed to go to sphinx/ext/autosummary/generate.py
and set imported_members=True
in the function generate_autosummary_docs
.
If you're not using numpydoc
like me, you might need to remove the .. HACK
directives.