Switch documentation to mkdocs + mkdocs material

[schlegelp]

This is a pain in the neck but I think migrating to mkdocs would pay off in the long run:

1. The build process is so much smoother and faster than Sphinx + RTD (live preview!)
2. Much more modern look and feel
3. API documentation (via mkdocstrings) is just incredible
4. Markdown instead of freaking RST

and the lost goes on....

As an example, check out the docs for Octarine I cobbled together over a weekend.

[ceesem]

Having started down this path ourselves, it's less of a pain in the neck than you'd think and this sort of conversion is exactly in the wheelhouse of LLMs.

[schlegelp]

My biggest grievance with mkdocs is that the HTML produced from Jupyter notebooks (which I use for the tutorials because they can also be tested) just looks atrocious.

[bdpedigo]

are you using one of these? https://mkdocs-jupyter.danielfrg.com/demo-nb/ https://github.com/greenape/mknotebooks

[schlegelp]

I've used the former but the latter also looks familiar - probably tried it out and ran into some issue.

[schlegelp]

Note to self: I think I like mdocs-gallery - it looks visually clean. It would mean rewriting the Jupyter notebooks to simple Python scripts (using the #%% syntax to label markdown) but we'd still be able to test against them.

[bdpedigo]

ive used this to convert https://jupytext.readthedocs.io/en/latest/formats-scripts.html so that would make the conversion easy!

[schlegelp]

FYI, preview version here: https://navis-org.github.io/navis/

I managed to solve/work-around most of the problems I encountered along the way - will put details in the PR. There are still a bunch of tutorials to migrate and docstrings to update.