Migrate from nbsphinx/jupyter-sphinx to myst_nb

[VeckoTheGecko]

Description

Here we migrate from jupyter-sphinx to myst_nb.

First I found all files with jupyter-sphinx directives, used rst2md on these files, and then went through manually fixing errors using sphinx-build -W (fail on warning) so that we have no more warnings.

TODO:

• Visual side-by-side checks
  • We want to make sure that in migrating to Myst that our documentation looks the same (i.e., no broken formatting, missing code blocks, or other visual regressions). A side by side checker like https://pianomister.github.io/diffsite/ is useful to use (use side-by-side or blend mode). The links below lead to the individual pages, with main on the left and this PR on the right.
  • doc/get-help/faq.md (view visual diff: main | this PR)
  • doc/getting-started-guide/quick-overview.md (view visual diff: main | this PR)
  • doc/internals/duck-arrays-integration.md (view visual diff: main | this PR)
  • doc/internals/how-to-add-new-backend.md (view visual diff: main | this PR)
  • doc/internals/how-to-create-custom-index.md (view visual diff: main | this PR)
  • doc/internals/internal-design.md (view visual diff: main | this PR)
  • doc/internals/time-coding.md (view visual diff: main | this PR)
  • doc/internals/zarr-encoding-spec.md (view visual diff: main | this PR)
  • doc/user-guide/combining.md (view visual diff: main | this PR)
  • doc/user-guide/complex-numbers.md (view visual diff: main | this PR)
  • doc/user-guide/computation.md (view visual diff: main | this PR)
  • doc/user-guide/dask.md (view visual diff: main | this PR)
  • doc/user-guide/data-structures.md (view visual diff: main | this PR)
  • doc/user-guide/duckarrays.md (view visual diff: main | this PR)
  • doc/user-guide/groupby.md (view visual diff: main | this PR)
  • doc/user-guide/hierarchical-data.md (view visual diff: main | this PR)
  • doc/user-guide/indexing.md (check for the linebreaks within the table, check that the numbering works and the code blocks) (view visual diff: main | this PR)
  • doc/user-guide/interpolation.md (view visual diff: main | this PR)
  • doc/user-guide/io.md (view visual diff: main | this PR)
  • doc/user-guide/pandas.md (view visual diff: main | this PR)
  • doc/user-guide/plotting.md (view visual diff: main | this PR)
  • doc/user-guide/reshaping.md (view visual diff: main | this PR)
  • doc/user-guide/testing.md (view visual diff: main | this PR)
  • doc/user-guide/time-series.md (view visual diff: main | this PR)
  • doc/user-guide/weather-climate.md (view visual diff: main | this PR)
• Check doc build time before and after
• Cleanup conf.py

Separate issue/PR

• Look into terminology.rst

  • is it possible to use the codeblocks run in CI here even though its nested?
  • if we can update this file, we can get rid of the jupyter-sphinx dependency

• Update contributing guidelines

Regressions - general

• Notebooks in the examples/* folder no longer have the nbsphinx prolog linking to the binder instance

Regressions - visual

Nested code cells not possible - code cells have been moved outside admonitions

Was getting the following errors:

/Users/Hodgs004/coding/repos/xarray/doc/user-guide/plotting.md:392: WARNING: Found an unexpected code-cell or raw-cell directive. Either this file was not converted to a notebook, because Jupytext header content was missing, or the code-cell was not converted, because it is nested. See https://myst-nb.readthedocs.io/en/latest/authoring/text-notebooks.html for more information. [mystnb.nbcell]

indicating code cells in admonitions aren't possible.

See 12a18f9 for all items changed.

I think this error is from myst_nb and integration with Sphinx, and is not a problem with the myst language or tooling that uses native myst doc builders (looking at the Myst guide this cell in callout is possible).

Nested code cells not possible - tabbed sections with code blocks now just separate headings

(similar to above regression)

Checklist

• towards Migrate from nbsphinx to myst, myst-nb #7924 (will close once we get rid of all rst?)
• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst
• New functions/methods are listed in api.rst

AI Disclosure

• This PR contains AI-generated content.
  • I have tested any AI-generated content in my PR.
  • I take responsibility for any AI-generated content in my PR. Tools: Claude - very minimal

[eni-awowale]

I don't know how long ago this was written but we do now automatically interpret CF conventions for the zarr backend. But maybe this means something else?

[VeckoTheGecko]

I mean, we understand CF time conventions but that's about it no? We don't go for the iris approach of understanding more cf conventions.

I agree though that maybe the wording here can be improved. For a future PR if you have ideas?

[VeckoTheGecko]

Thanks for the review @eni-awowale ! I have finished going through all the pages that were changed, fixing a handful of (some pre-existing) rendering issues.

The only regressions we have are documented in the PR description now.

Is there anything else that we should consider before merging this?

• Check doc build time before and after

Checking the logs on RTD, it looks like the build time dropped from 11min to about 9.5min

[eni-awowale]

This is awesome 🦎!

I think the latest commit broke the docs build? I was able to get the docs for the PR before.

[VeckoTheGecko]

Fixed the build, thanks!

Do you have any opinions on the regressions? I think we're good to go right? (though maybe we leave this open for a couple days in case maintainers have other comments)

[eni-awowale]

For the regressions with the warnings maybe it would be clearer to have the python code outside of the warning admonition? So the warning reads more like a sub-header for that section and it is more consistent with how it is done with the note admonition regression you showed.

I don't really have strong opinions either way, so i think it's good to go! But it might be nice to leave this open and see if other folks have any other ideas.

EDIT:
Idk if the error you mentioned can't be duplicated locally but when I add a code cell to the admonition it works and renders correctly?

[VeckoTheGecko]

Idk if the error you mentioned can't be duplicated locally but when I add a code cell to the admonition it works and renders correctly?

Hmmm, how are you adding the code cell?

I was doing it via

````{note}

Some admonition body

```{code-cell}
print("some code")
```

````

And that wasn't working for me

[eni-awowale]

this is what i did:

````{warning}
Do not try to assign values when using any of the indexing methods `isel`
or `sel`:

```python
# DO NOT do this
da.isel(space=0) = 0
```

Instead, values can be assigned using dictionary-based indexing:

```python
da[dict(space=0)] = 0
```

Assigning values with the chained indexing using `.sel` or `.isel` fails silently.
See the cell below:

{code-cell}
da = xr.DataArray([0, 1, 2, 3], dims=["x"])
# DO NOT do this
da.isel(x=[0, 1, 2])[1] = -1

````

[VeckoTheGecko]

That doesn't work for me @eni-awowale :/ . Could you try pixi run doc-clean?