WIP: Version placeholders in repo

[jo-mueller]

So...since updating version keys across the project already bit me a few times, this would be a solution to starting having this key replaced by a placeholder in the various places where it occurs.

I have added a new function in the _prebuild.py script, that goes through all json in the examples dir, searches for "{{ VERSION }}" and replaces it with whatever is written in _version.py, so that would be the only place in the future where the version would need to be updated. For this to work, all the json examples need to sit in a examples/_static directory and the updated json files are then kept at examples/_build.

To be considered: It would be nice to have this ´_version.py´ under the control of a versioning tool like setuptools_scm, but these fundamentally conflict with versions that have .dev in them. So if we wanted to do this in the future, maybe we should think about a different tag. But maybe just updating the version in a single file wouldn't be too much overhead 🤷

This is to be done with

• json files under examples/
• index.md (The actual spec)
• json file in tests

This PR will conflict big time with #140 , so I would opt for that to go in first and then I'll continue here or I'll rebase right away.

cc @jni

[github-actions]

Automated Review URLs

• Readthedocs

[jo-mueller]

In the RTD preview build, it comes out alright :)

[jni]

Oh amazing, I would have loved to have this for #190 LOL.

[jo-mueller]

Oh amazing, I would have loved to have this for #190 LOL.

Right? It's very annoying to replace all the versions everywhere and a perfect source for mistakes.

[clbarnes]

Points I made in sync:

1. Yes please, not having to do a ton of version replacement and adding that git churn would be great
2. I'm wary about mixing template files and non-template files without clearly marking which are which. I think if we're doing templating, we should do templating. I would suggest minijinja, which is a simplified dialect of the well-known jinja2 system with broad language support (albeit some of it vibe-coded, although by a very competent developer) and high-performance implementations. There is a sphinx plugin (confusingly called jinja2, despite not using jinja2) which has direct support for MyST markdown. Slight annoyance is that adding .template (or .jinja) everywhere may break some IDE auto-highlighting and previewing.