Switch documentation generator/host?

[billbrod]

Documentation has two decision points: generator and host. For generator, the choices are mkdocs and sphinx. For host, github-pages or readthedocs.

I think switching from sphinx to mkdocs is worth doing, because it handles notebooks in a cleaner way and uses markdown by default. Has a similar mkdocs gallery and ability to generate from plots.

For gh-pages vs readthedocs: gh-pages consolidates all actions onto github and makes it a bit simpler. readthedocs requires an extra step to link, but allows for building preview documentation for each pull request, which is worth it.

[billbrod]

I'm now leaning towards sticking with sphinx (because it's more robust, more plugins, has been around for longer) but switching to markdown, and so using the Myst parser