-
-
Notifications
You must be signed in to change notification settings - Fork 2.4k
By default, make Autosummary templates generate documentation pages for classes, functions, exceptions etc #7912
Description
Is your feature request related to a problem? Please describe.
The new :recursive: option for sphinx.ext.autosummary is great. I can point Sphinx at the top of my package and have it find every module, however deeply nested. For each module it creates neat summary tables listing all the attributes, classes, exceptions and functions in those modules. This is all fantastic.
To generate actual documentation pages for these attributes, classes, exceptions and functions, however, and link to them from the summary tables, I have to copy the default module.rst and class.rst templates locally and edit them. I would like to think this is what most people would want. So I think it should be the default behavior - and those who don't want this should have to customize the templates.
Describe the solution you'd like
I've described the solution I'd like to see here. There's a Github test implementation here and a sample ReadTheDocs user experience here.
(I'm sure you know what the current user experience is like but, just to be clear, you can reproduce it by cloning the Github test project and deleting the :template: custom-module-template.rst line in docs/source/index.rst.)
Basically, the solution involves adding a :toctree: option to every .. autosummary:: directive in the default module.rst template so that documentation pages get generated for attributes, classes, exceptions and functions out-of-the-box, like this:
site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst (additional lines noted on right):
{{ fullname | escape | underline}}
.. automodule:: {{ fullname }}
{% block attributes %}
{% if attributes %}
.. rubric:: Module Attributes
.. autosummary::
:toctree: <-- add this line
{% for item in attributes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block functions %}
{% if functions %}
.. rubric:: {{ _('Functions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in functions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block classes %}
{% if classes %}
.. rubric:: {{ _('Classes') }}
.. autosummary::
:toctree: <-- add this line
{% for item in classes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block exceptions %}
{% if exceptions %}
.. rubric:: {{ _('Exceptions') }}
.. autosummary::
:toctree: <-- add this line
{% for item in exceptions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
{% block modules %}
{% if modules %}
.. rubric:: Modules
.. autosummary::
:toctree:
:recursive:
{% for item in modules %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}