Description
Describe the bug
https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata documents env_version.
-
It says:
[...] env data structure if the extension stores any data to environment
... but it gives no indication how/why to do that. It could e.g. link to https://www.sphinx-doc.org/en/master/development/tutorials/todo.html
-
It says:
If not given, Sphinx considers the extension does not stores any data to environment.
... but it doesn't say if that includes a
Domain(https://www.sphinx-doc.org/en/master/extdev/domainapi.html) defined by the extension. I assume that the domain is somehow stored in the environment, but I guess it doesn't need to be reflected inenv_versionbecause it tracks its own structure with thedata_versionattribute?- in the meantime it has been clarified that this is about actively storing stuff in the "
envobject", and not about more generally "in the environment", so I think this should be clear now.
- in the meantime it has been clarified that this is about actively storing stuff in the "
-
https://www.sphinx-doc.org/en/master/development/tutorials/todo.html shows an extension that stores data in the environment, but it does not return
env_versionin itssetup()function!- potential fix: #12349
-
https://www.sphinx-doc.org/en/master/development/tutorials/todo.html could mention that alternatively, a
Domaincould be used to store data in the environment. It could link to https://www.sphinx-doc.org/en/master/development/tutorials/recipe.html, which provides an example for that. -
https://www.sphinx-doc.org/en/master/development/tutorials/recipe.html does not mention
data_version, which is of course not strictly necessary, but I think it might be a good idea to recommend specifying it, to make it easier to not forget bumping it once there are changes to the data at a later time.- potential fix: #12350
-
This has nothing to do with
env_version, but looking at the tutorials, I have seen that https://www.sphinx-doc.org/en/master/development/tutorials/autodoc_ext.html does not setparallel_read_safebut I guess there is no reason for this extension to disable parallelization, right?- this was fixed in #12288
-
The docstring of
Domaindoesn't give any information whether it is recommended to use it to store arbitrary data (see https://github.com/sphinx-doc/sphinx/issues/12237#issuecomment-2047118111)
How to Reproduce
Look at https://www.sphinx-doc.org/en/master/extdev/index.html#extension-metadata