sphinx-doc / sphinx-doc/sphinx
By default, make Autosummary templates generate documentation pages for classes, functions, exceptions etc
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
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 %}
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst and inspect the existing autosummary blocks for attributes, functions, classes, and exceptions. Add the requested default navigation behavior consistently, then verify that recursive autosummary output generates linked documentation pages for those members without requiring a custom template.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 52/100