sphinx-doc / sphinx-doc/sphinx
A better way to store extension data on the environment
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Problem
The approach to storing extension data is explained only vaguely.
From the env-merge-info description and
the todo extension tutorial I infer that one has to add arbitrary attributes to the env object.
This doesn't look very clean. It risks breaking the object and one has to be careful that the data is already added (lots of hasattr() checks).
Proposal
- Add a dict
env.extension_dataand recommend extensions writing there. - Can one initialize the extension data instead of checking in various places if it exists? Would
env-before-read-docsthe right place? I.e.
def setup(app):
...
app.connect("env-before-read-docs", setup_data)
def setup_data(app, env, docnames):
env.extension_data['todo_all_todos'] = []
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 by reading the env-merge-info description and the todo extension tutorial linked in the issue, then trace the env-before-read-docs setup_data entry point. Determine how extension data should be initialized and persisted without arbitrary environment attributes or repeated hasattr() checks. Done means the extension API and initialization guidance clearly support a shared extension_data dictionary.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- developer-experience, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100