sphinx-doc / sphinx-doc/sphinx

A better way to store extension data on the environment

Open
#9,003 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

domain internals:environment internals:parallel type:enhancement
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_data and recommend extensions writing there.
  • Can one initialize the extension data instead of checking in various places if it exists? Would env-before-read-docs the 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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.