sphinx-doc / sphinx-doc/sphinx

Allow overriding of default config values.

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

Nobody has claimed this yet.

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.

I'm currently working on a custom theme and want to override a config default value. When calling app.add_config_value in my setup function, i get ExtensionError from Config.add.

Describe the solution you'd like

It would be nice if Sphinx.add_config_value respective Config.add accepts a flag whether to override the value if it already exists.

Describe alternatives you've considered

As workaround i update the value on Config.values directly, but i consider it a hack.

def setup(app):
    ...
    hpi = app.config.values['html_permalinks_icon']
    app.config.values['html_permalinks_icon'] = ('#', hpi[1], hpi[2])

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 by tracing Sphinx.add_config_value and Config.add, focusing on how existing configuration names produce ExtensionError. Review the Config.values workaround in the issue and the surrounding configuration behavior. Done means an explicit override option is supported without breaking existing defaults or duplicate-name handling.

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
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.