update backends tutorials intro

[JessicaS11]

Navigating Xarray backends (engine="rioxarray") when using xr.open_dataset() can be confusing. One way to help clarify is by guiding the user through determining if the engine they need exists and is built-in, available from another library, or needs to be created. Here we introduce a flowchart to help guide that process.

[dcherian]

Nice. Shall we stick this in the main docs instead? https://docs.xarray.dev/en/stable/user-guide/io.html

It strikes me that that page is also missing a nice intro ;)

[JessicaS11]

Nice. Shall we stick this in the main docs instead? https://docs.xarray.dev/en/stable/user-guide/io.html

It strikes me that that page is also missing a nice intro ;)

Agreed... I can see some good arguments for this material (text and diagram) to go directly into the docs, and then this tutorial page just becomes a really short pointer to the docs page and the subsequent examples. Happy to move accordingly but wanted to keep refining the content while we decide.

[JessicaS11]

@TomNicholas @scottyhq @negin513 @betolink Since this was ideated (thanks, Tom!) at our SciPy2024 tutorial planning meeting - any thoughts on where this diagram lives (docs versus tutorial, with a link from the other)?

[JessicaS11]

Can anyone help with the configuration options to get this building? To use the sphinxcontrib.mermaid extension, myst-parser is needed, but as soon as I added that I started getting an ".md extension already registered" error that I can't figure out how to resolve.

[scottyhq]

Can anyone help with the configuration options to get this building? To use the sphinxcontrib.mermaid extension,

I'm hoping #270 (bumping sphinx versions) will just remedy this! I'll try to dig into it a bit more soon

[JessicaS11]

I'm hoping #270 (bumping sphinx versions) will just remedy this! I'll try to dig into it a bit more soon

After some more thought and discussion with others, I'm going to move the diagram and some of this intro content to the docs as suggested by @dcherian. Then I'll revamp this PR to have a shorter intro that links to those pages.

[JessicaS11]

See also (which will need to be merged before this PR): pydata/xarray#9175

[github-actions]

♻️ PR Preview daa22e6 has been successfully destroyed since this PR has been closed.

_{🤖 By surge-preview}

[JessicaS11]

@scottyhq @dcherian I think this is ready for review... I'd love confirmation that the list of built-in engines is right, because we've got different info in different places.

[scottyhq]

Thanks for this! I think the content flows better top to bottom and the flowchart in the main Xarray docs is great.