search

pydata / xarray

N-D labeled arrays and datasets in Python
https://xarray.dev
Apache License 2.0
3.55k stars 1.07k forks source link

Migrate from nbsphinx to myst, myst-nb #7924

Open dcherian opened 1 year ago

dcherian commented 1 year ago

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. (#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 commented 1 year ago

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

DocOtak commented 1 year ago

Would docstrings in the code also be written in MyST?

shoyer commented 1 year ago

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: https://github.com/executablebooks/MyST-Parser/issues/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 commented 1 year ago

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.