Move documentation to sphinx-book-theme and myst

[rhugonnet]

This PR updates xDEM's documentation format and theme, finishes fixes with the new GeoUtils behaviour (#341) and finishes the setup of Binder.

It largely mirrors GlacioHack/geoutils#351 on all documentation aspects, see that PR for reference.

In short:

• No content is changed, simply the theme to sphinx-book-theme and the format to myst,
• Configuration of sphinx is refined,
• Setup for readthedocs are improved,
• The codes in /docs/source/code used to populate some pages have been moved directly into the documentation as myst-nb code-cells,
• Any documentation page with code can now be launched as a notebook in Binder.

A couple notable addition of this PR:

• It refactors xdem/docs/ into xdem/doc/ for consistency with GeoUtils, and other packages,
• It adds "dollarmath" to myst_enable_extensions in the documentation configuration to represent equations,
• It rewrites the README and CONTRIBUTING in the same style as for GeoUtils, with several new badges.

Issues solved

This PR:

• Resolves Increase width of doc #295,
• Resolves Make xdem convertible to binder #296

Old text

Here's an example of the new documentation, especially the updated "About xDEM" page with some functionalities of sphinx-book-theme such as margin admonitions or sidenotes:
https://xdem-rhugonnet.readthedocs.io/en/doc_booktheme/about_xdem.html

What improvements we'd be looking at:

• The look is cleaner, with a width/font ratio slightly larger to avoid long pages, which partially solves Increase width of doc #295;
• The theme comes with a lot of practical options for documentation: direct link to open an issue from the doc, downloading any page in RST/PDF, and launching an interactive code with a Binder from the doc, which would solve Make xdem convertible to binder #296;
• The theme support margin sidenotes, figures, or admonitions, which are kept on the side for a cleaner read on wide screens, but collapse in-line on narrower screens (e.g., mobile), which further solves Increase width of doc #295 of the readthedocs theme.
• The theme relies on MyST markdown (see https://myst-parser.readthedocs.io/en/latest/), which allows for a bit more that classic markdown or reStructuredText. It only parses .md files differently, leaving our current .rst files interpreted in HTML the same. We can easily transition all files using rst2myst (see https://rst-to-myst.readthedocs.io/en/latest/).
• The theme has a good, growing community behind it. Recently, the parent pydata-sphinx-theme added support for a "dark-theme toggle" functionality, which will soon be inherited by the sphinx-book-theme as well, and save our eyes while working on the docs! 😄

[adehecq]

Great initiative ! A few comments:

• It will take me some time to get used to the new theme... but it does not mean we should not change it 🙃
• Indeed, the theme is very white/bright. I liked that the previous one was a bit darker. Can we already try the dark mode? Or can we set a different color for the side columns?
• The side notes are a cool feature, but we should not overuse them. The "About xdem" page you made is nice, but there is a lot of information in an unordered way, so I find it a bit more difficult to read.
• Very importantly, this PR will not solve Make xdem convertible to binder #296. It will just make it easier to link it to Binder, but we still need to setup the binder configuration.

[rhugonnet]

Short answers:

• Dark mode should come around in a few months normally, they are working on it but it's mostly inheritance from the parent theme so not too much work,
• Yes, the "About xDEM" page is just to give an example (although it's not too much info for me, but definitely at the upper limit).

Well you will probably have to get used to it anyway, as it's the theme of any major PyData package: NumPy, SciPy, Dask, etc 😛

Personally, I find it on a different level (much, much better) than the ReadTheDocs theme, which is extremely narrow on modern monitors (bad use of space), unintuitive for search features, no interactive options, less customizable and less maintained... And not only the look, but the experience from coding in rSt on the Sphinx side is not the best, I think MyST would be a much better experience (we are already used to Markdown with GitHub, don't need to learn yet another language with rSt...).

[rhugonnet]

Merging now as no documentation content is changed and the final fixes are required to make tests pass.

[adehecq]

Nice to have both documentations updated now ! 🥳

• The theme comes with a lot of practical options for documentation: direct link to open an issue from the doc, downloading any page in RST/PDF, and launching an interactive code with a Binder from the doc, which would solve Make xdem convertible to binder #296;

Maybe I missed something, but I couldn't find a button to start a binder from one of the examples (e.g. this one).
Can you explain how to start a binder?

[rhugonnet]

The binder works from documentation pages, but not from the gallery of examples (because those are generated by sphinx-gallery, not myst-nb).

Right now, sphinx-gallery does not support anything else than rst, and Binder support is experimental: https://sphinx-gallery.github.io/stable/configuration.html#binder-links
We could move our sphinx-gallery examples to Jupyter notebooks and run them directly with myst. They would look the same in the docs. But we would lose all the benefits from sphinx-gallery (having examples linked to the API, being able to show mini-galleries for any class/function, etc...)

I wonder what's the best way to go about this... 😅
What are your thoughts @erikmannerfelt @adehecq?

[rhugonnet]

Unfortunately, sphinx-gallery + Binder does not work with readthedocs (last paragraph of the section at the link in previous comment):

It is not currently possible to host notebooks generated by Sphinx-Gallery with readthedocs.org, as RTD does not provide you with a GitHub repository you could link Binder to. If you’d like to use readthedocs with Sphinx-Gallery and Binder links, you should independently build your documentation and host it on a GitHub branch as well as building it with readthedocs.

Looking deeper, it looks like they are thinking of making the link easier in sphinx-gallery, but no PR on this is ongoing, so it might take a while (for instance: sphinx-gallery/sphinx-gallery#603).

Looks like it is possible to somehow circumvent the problem in the meantime: https://stanczakdominik.github.io/posts/simple-binder-usage-with-sphinx-gallery-through-jupytext/

[rhugonnet]

@adehecq @erikmannerfelt @atedstone You probably received the Readthedocs email saying that build.image is deprecated and needs to be changed to build.os in readthedocs.yaml, and that this impacts our Readthedocs projects (details here: https://blog.readthedocs.com/use-build-os-config/).
Thankfully, the changes to the new syntax were already made in April in geoutils/xdem when I updated the readthedocs.yaml to use mamba-forge, so it's all good!
We'll keep receiving Readthedocs emails until the final phase of migration mid-October in any case.

[adehecq]

Thanks @rhugonnet for looking into the Binder issue. It seems quite complicated indeed and probably not worth the huge effort. Another option is to have a separate repository with some demo files, like I did for the winter school in Nepal: https://github.com/GlacioHack/xdem-demo. Each project can be a different branch.

And thanks for looking into the readthedocs warning!

[rhugonnet]

This makes me think: for binder, we cannot rely on the current system anymore, they have lost most of their servers. I'll open an issue.