sphinx-doc / sphinx-doc/sphinx

Allow autosummary to generate stub pages without toctree items

Open
#9,726 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autosummary internals:toctree type:enhancement
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:

https://github.com/sphinx-doc/sphinx/blob/56f97d71a2b1733ebf401d357a634e2d7e4c896e/sphinx/ext/autosummary/templates/autosummary/base.rst#L1-L3

(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:

https://github.com/sphinx-doc/sphinx/blob/56f97d71a2b1733ebf401d357a634e2d7e4c896e/sphinx/ext/autosummary/__init__.py#L120-L127

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.