Incomplete documentation for env_version about sphinx HOT 7 OPEN

@chrisjsewell You introduced the typed interface for that one so perhaps you could take that one?

from sphinx.

you introduced the typed interface for that one so perhaps you could take that one?

Well, that's one of the reasons I introduced it; because for a long time I had no idea env_version was even an option 😅
But indeed thank you for detailing this @mgeier, it would be good to make the documentation around it clearer

alternatively, a Domain could be used to store data in the environment.

I would note here, that I feel the purpose of a domain is more around handling referencing, and then the storage of data here is more of a "side-effect" of that; to store pointers to targets, etc
I don't believe you should use it to store arbitrary data.

from sphinx.

I don't believe you should use it to store arbitrary data.

This kinda says the opposite: #9003 (comment)

Would you suggest adding arbitrary attributes to app.env instead?
Or do you have something even better?

And it's not only about storing data, it's also about making it work with parallel builds, which is actually hard, see e.g. #12251.

And to be fancy, it's about removing the appropriate data if a source file is removed (which the "todo" extension does but the "recipe" extension doesn't, AFAICT).

For a concrete example, see mgeier/sphinx-last-updated-by-git#66. I'm not sure if that's better or worse, BTW!

from sphinx.

This kinda says the opposite

well that is not consistent with what the actual source says:

And it's not only about storing data, it's also about making it work with parallel builds, which is actually hard

We deal with this in sphinx-needs with parallel builds for large documentation sets, and it works quite well: https://github.com/useblocks/sphinx-needs/blob/0f71ecde47a3f7c3245c5bcf545ef5281376768c/sphinx_needs/needs.py#L266-L270

But I agree that it would be nice to have a "consistent" workflow for storing data (outside of references)

from sphinx.