sphinx-doc / sphinx-doc/sphinx

No way to access the builder in directives

Open
#14,136 13 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

priority:high type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

I was asked in https://github.com/sphinx-doc/sphinx/issues/13072#issuecomment-3594904760 to open a new issue for this

Describe the bug

With the new logic discussed in #13072 I don't see a way how a directive can access the builder, to access e.g. app.builder.outdir and app.builder.name. The app can currently be fetched over self.state.document.settings.env.app which won't then work anymore.

You can find my code here: https://github.com/SAP/swagger-plugin-for-sphinx

How to Reproduce

n/a

Environment Information
Platform:              linux; (Linux-5.14.21-150500.55.124-default-x86_64-with-glibc2.31)
Python version:        3.14.0 (main, Nov 10 2025, 09:33:32) [GCC 7.5.0])
Python implementation: CPython
Sphinx version:        9.0.0
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.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 reading the discussion in #13072 and the directive usage in the linked swagger-plugin-for-sphinx project; the issue does not name a Sphinx source file or test. Determine how directives should access the builder, including its outdir and name, and add coverage showing that this access works with the new logic.

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
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.