Migrate from nbsphinx to myst, myst-nb

[dcherian]

Is your feature request related to a problem?

I think we should switch to MyST markdown for our docs. I've been using MyST markdown and MyST-NB in docs in other projects and it works quite well.

Advantages:

1. We get HTML reprs in the docs (example) which is a big improvement. (Using the html repr in the documentation #6620)
2. I think many find markdown a lot easier to write than RST

There's a tool to migrate RST to MyST (RTD's migration guide).

Describe the solution you'd like

No response

Describe alternatives you've considered

No response

Additional context

No response

[shoyer]

I agree! I use MySt and MyST-NB for Xarray-Beam and it works quite well.

[DocOtak]

Would docstrings in the code also be written in MyST?

[shoyer]

Would docstrings in the code also be written in MyST?

This would be really nice, but I don't think there is good tooling for it yet. It looks like there is an open issue for parsing Markdown docstrings with MyST: executablebooks/MyST-Parser#228

We use napoleon for parsing docstrings in our docs, which supports the NumPy and Google docstring conventions. We currently use the NumPy docstring convention which expects RST.

The Google docstring convention is rather different (I actually like it better), and I've seen people use markdown with it before. But I don't think tools like Napolean support that (yet).

[benbovy]

I also use MyST and MyST-NB and I like it a lot!

It seems that the maintainer MyST-NB has stepped down from that project as well as a few other projects (including the tool to migrate from RST to MyST), though, which causes some issues of dependencies that are still upper bounded to old versions (e.g., sphinx < 6, myst-parser, ipython, etc. See all open PRs). It is not yet clear to me if someone else will take over the maintenance in the short term.