Description
Is your feature request related to a problem? Please describe.
The project has several central internal types, Sphinx
, BuildEnvironment
, Domain
(& subclasses), and Project
.
Of these, only Project
is well-isolated from the rest of the classes. Creating a Sphinx
object internally creates a BuildEnvironment
object, which in turn creates an instance of all 10 builtin domains. All of this happens within Sphinx.__init__()
and creates mutual dependencies between app
, env
, and each domain. This also happens to a lesser extent with the Builder
object.
This design makes it hard to effectively seperate concerns. It makes designing a better parallel system harder, and means that testing/mocking parts of the application is much harder than it could be.
I would like to see if there is a realistic way we can uncouple these mutual dependencies, and provide a migration path for downstream extensions.
Describe the solution you'd like
My current idea is to break BuildEnvironment
into three parts:
- A dataclass with information about the current document (all that is currently the
env.tmp_data
dict. - A dataclass with information about the build at large
- A type that provides utility functions and contains the current-document and global dataclasses.
I believe this would allow us to pass around the data objects and effectivley construct BuildEnvironment
accessor/wrappers on the fly where needed. For example, we can pass Domain.__init__
the domaindata
dict as part of the global dataclass, instead of the entire env object as at present.
I am very open to other ideas though, as there may be approaches I haven't considered. Keeping backwards compatibility and providing a migration path for downstream users will be key, but I think should be doable with clever use of __getattr__
etc.
Describe alternatives you've considered
Do nothing. The easiest option, but leaves us in a less-than ideal situation.
cc: @sphinx-doc/developers
- Create a new type for the current document's environment state #13151
- Highlighting appears to be lost for code-blocks from markdown sources with Sphinx v8.2.0+/e65bbb96a and myst_parser #13207
- Avoid attribute indirection with
env
#13212
A