sphinx-doc / sphinx-doc/sphinx
Allow autosummary to generate stub pages without toctree items
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.
Autosummary with the :toctree: option is a really useful way of generating "stub pages" for modules/classes/etc. However, for libraries with a large API surface area, it generates a ton of extra stub pages that are linked in the TOCTree. If you use a theme that has collapsible navigation, and thus includes all pages as links in every sidebar, then this drastically slows down the documentation build and results in really large HTML files.
Describe the solution you'd like
I think an easy solution would be to allow for the autosummary directive to generate the stub files as orphans, so that they don't get linked in a toctree. I think this could be done by:
(1) adding a configuration value like autosummary_stub_files_only = True, and add a line like the following:
{% if config.autosummary_stub_files_only %}:orphan:{% endif %}
somewhere around here:
(2) turned off adding these files to the toctree in the python logic. maybe somewhere around here (?) but I am not as familiar with this codebase:
Describe alternatives you've considered
The alternative is to work around this with docs-specific config or extensions. I actually have a little extension that exists to get around this problem here:
https://github.com/executablebooks/sphinx-remove-toctrees
however, I think it'd be best if this didn't require a dedicated extension just to remove some toctrees. I would be happy to deprecate it in the future if this were natively supported :-)
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 sphinx/ext/autosummary/templates/autosummary/base.rst and the autosummary logic around sphinx/ext/autosummary/init.py lines 120-127. Trace how stub files are generated and added to the toctree. Done means autosummary can generate orphan stub pages without adding them as toctree items, while retaining the existing behavior by default.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100