sphinx-doc / sphinx-doc/sphinx
Allow disabling default substitutions in the config
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.
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
- possibly related discussion: https://github.com/sphinx-doc/sphinx/issues/2173
- definition in the source code: https://github.com/sphinx-doc/sphinx/blob/f85f50e/sphinx/transforms/__init__.py#L37-L42
- https://github.com/pytest-dev/pytest/issues/12538
cc @RonnyPfannschmidt
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 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