Start Executing Docs

[ianhi]

Beginning of executable docs (#83). All notebooks will automatically be executed as part of the docs build per the docs here: https://myst-nb.readthedocs.io/en/latest/computation/execute.html#

It will be useful to set up the build failing on unexepcted errors per the docs here: https://myst-nb.readthedocs.io/en/latest/computation/execute.html#error-reporting-warning-vs-failure

Currently has multiple errors in the usage.ipynb file @TomNicholas

[TomNicholas]

This is great, thank you @ianhi !

Can you just explain how (if at all) this interacts with our CI? I see you can locally configure to automatically rebuild the docs but will these executable docs automatically get rerun by our docs CI? Or should we add that in a follow-up?

[ianhi]

The readthedocs build will fail if there is an error, then when you push an update (that hopefully resolves things!) it will run again.

[maxrjones]

thanks for working on this @ianhi! I wanted to let you know of a couple necessary changes related to https://github.com/zarr-developers/VirtualiZarr/pull/407 (sorry for the extra work):

• dependency groups can now be added to the docs environment by modifying this line, rather than using doc.yml. Based on the changes in your PR, it looks like you'll want to add at least "hdf", "hdf5", "icechunk", "kerchunk", "hdf5-lib".
• I also included a pixi task for serving the documentation (see https://virtualizarr.readthedocs.io/en/latest/contributing.html#build-the-documentation-locally, but please revise as needed).

Is there a way to execute the markdown code snippets directly rather than converting all the markdown files to Jupyter notebooks?

[maxrjones]

Hey @ianhi, thank you for your work on this. I am going to close the PR because with mkdocs we no longer need to rely on Jupyter Notebooks to execute docs. I'd definitely welcome your help making the code snippets executable using markdown-exec.