sphinx-doc / sphinx-doc/sphinx

Allow disabling default substitutions in the config

Open
#12,480 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

internals:config type:proposal
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.

When setting things like release to dynamically-generated versions like the ones produced from Git via tools like setuptools-scm, this results in cache invalidation on every single build, effectively rendering it unusable.

Describe the solution you'd like

Projects that don't make use of substitutions like |release| / |version| in their RST files, should be able to disable those so they don't influence the cache and let it be reused.

Describe alternatives you've considered

Setting release and version to static values, but that's not desired.

Additional context

cc @RonnyPfannschmidt

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 the default substitution definition in sphinx/transforms/init.py, especially the lines linked in the issue, and trace how release and version affect configuration and cache invalidation. Determine where a configuration option can disable these substitutions, then verify that builds without their use can reuse the cache while existing substitution behavior remains unchanged.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.