WIP: Use mkdocs-material for documentation

[maxrjones]

I haven't updated all the pages yet for the new format, so please don't nit yet but I'd really appreciate some high level feedback on using mkdocs material and plugins to address #500 and #83.

Here's the preview: https://virtualizarr--606.org.readthedocs.build/en/606/

FWIW I prefer the style the mkdocs style over sphinx and find it easier to navigate with the page nav on the left and section nav on the right. I also prefer executable markdown cells over needing to convert the files to Jupyter notebooks.

[TomNicholas]

I was secretly hoping you would do this @maxrjones 😆

It looks beautiful!

find it easier to navigate with the page nav on the left and section nav on the right.

This is definitely an improvement.

I also prefer executable markdown cells over needing to convert the files to Jupyter notebooks.

Are cells being executed in the generation of these docs? I know that in #486 we found that there were a few bugs in the executable code examples. If possible I think having one PR that changes the docs format and a follow-up that makes cells executable would be the easiest way.

[maxrjones]

Are cells being executed in the generation of these docs? I know that in #486 we found that there were a few bugs in the executable code examples. If possible I think having one PR that changes the docs format and a follow-up that makes cells executable would be the easiest way.

The cells in docs/index.md are run (you can see 'exec=true') as a proof of concept. It's pretty nifty because you can define a session that's shared across multiple cells. It's also set that the output is html, but I'm not sure if xarray can return nicer htmls for virtual datasets. Probably something to improve separately.

I'm a fan of leaving the execution of other cells to a separate PR to save some time.

[TomNicholas]

I'm not sure if xarray can return nicer htmls for virtual datasets

That would require virtualizarr to define a html representation of a ManifestArray, and xarray to use that in it's html repr. Could be cool, which is why I suggested it in #59 😉