Start of executable docs

[ianhi]

By making docs executable we will be able to automatically pick up errors. Currently I'm doing this using markdown-exec because that was the only way to integrate into the existing markdown docs while also preserving the tabbing that exists in several pages. This has the downside of currently being a bit verbose in adding to the start of each executable codeblock. However I think this is fixable with some issues I've opened upstream (pawamoy/markdown-exec#77, pawamoy/markdown-exec#76 (comment)). There are two alternatives:

1. mkdocs-jupyter

Woudl allow for writing documentation in jupyter notebooks. however, we would lose some of the pymdownx extensions (e.g. tabbing)

2. Switching the docs build to sphinx and using myst would allow for writing everthign in jupyter as well as preserving tab behavior. However, this would require swapping the docs framework.

Have doc build fail on unexpected error:

markdown-exec currently warns on an unexpected error. We can make the docs fail by passing --strict to mkdocs build (pawamoy/markdown-exec#75)

Alternatively mkdocs-jupyter provides this already, or we can achieve the same with myst/jupyterbook

[ianhi]

Ahh annoyingly this requires readthedocs to know how to install the dev version of icechunk, otherwise it won't be able to properly execute the docs. may take some figuring out to make that happen in readthedocs with poetry etc

[dcherian]

How about

storage = icechunk.local_filesystem_storage(tempfile.mkdtemp()))

so we don't have to clear the local folder above?

[dcherian]

we can directly install from github with pip too if we know the commit ID. example:

pip install git+https://github.com/earth-mover/icechunk.git@COMMIT#subdirectory=icechunk-python

This will require maturin in the env, which we seem to have.