Domain index entries could be generated later in the build process

Open
#10,299 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
build-system

Research direction

Read the Builder.build flow, especially Builder.prepare_writing, Builder.finish, Builder.gen_indices, Builder.write_domain_indices, and Index.generate. Confirm how HTML-based builders currently use domain index class attributes, then defer generation until domain indices are written while preserving existing output and behavior.

Written by the indexing model from the issue text.

Description

type:enhancement

Is your feature request related to a problem? Please describe.

Domain index entries could be generated later in the build process.

Describe the solution you'd like

Domain indices, at least in HTML-based builders, are written during Builder.finish but generated during Builder.prepare_writing. In other words

# Abstract builder when applicable, else HTML builder
Builder.build()
├── ...
├── Builder.write()
│   └── Builder.prepare_writing()
│       └── Index.generate()                # Here domain index entries are generated.
└── Builder.finish()
    └── Builder.gen_indices()
        └── Builder.write_domain_indices()  # Here domain index entries are used.

During prepare_writing, some class attributes from each domain Index are used, but not the generated content. In other words, from what I have seen, the generated index entries could be generated (Index.generate()) directly during Builder.write_domain_indices()). In my opinion, it would make perfect sense to wait until the generated domain index entries are needed before generating them.

Also, this enable domains to provide a wider variety of features along with their Index.

Describe alternatives you've considered

Additional context
Add any other context or screenshots about the feature request here.

In case you would consider this acceptable, I would probably write a patch since the required changes in the code seams quite minor and safe at first sight

Dominant language
Python
Stars
8k
Forks
2.6k
No merged PRs in 30d

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.

More from sphinx-doc/sphinx

All issues in sphinx-doc/sphinx

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.