issue_comments

Thank you @keewis, @dcherian, @shoyer!

I plan to merge this later today (unless there's any objection and/or necessary changes)

The only issue I have with the new theme is that due to the maximum line length we use some examples have horizontal scroll bars (unless the left side bar is hidden).

@keewis, I fixed this issue.

@pydata/xarray, this PR is ready. Unless there's any additional issue that needs to be addressed before merging, feel free to merge this.

It'd be nice to get the left sidebar to "pin" like the right one. Right now if you scroll enough ,it disappears

@dcherian, this is fixed. When you get a moment, take another look and let me know if I missed anything.

@dcherian,

Can we add another level of organization to API reference in the sidebar: "Top-Level Functions", "Dataset" etc.?

It'd be nice to get the left sidebar to "pin" like the right one. Right now if you scroll enough ,it disappears

I have yet to figure this out. If someone knows how to do this (whether with or without custom HTML template), please let me know :)

Another minor comment: How about renaming "external resources" to "Tutorials & Videos"? Similarly "Related projects" to "Ecosystem"?

Done!

@keewis,

The only issue I have with the new theme is that due to the maximum line length we use some examples have horizontal scroll bars (unless the left side bar is hidden).

I will see if there's a remedy for this.

@pydata/xarray, this is ready for another round of reviews...

Is there a particular reason why we're moving away from nbsphinx?

I got a bit carried away when I saw the Markdown design document in https://github.com/pydata/xarray/pull/4979 :). I figured with myst/myst-nb, it would be easier to support documentation source written in any format (.md, .rst, .ipynb) in the future. I will revert back to nbsphinx ((the switch is probably not yet worth it).

unrelated to that: the internals page is a collection of mostly unrelated topics. It might be good to break it up into separate pages (e.g. "Variable", "duckarray integration", "accessors", "zarr spec", "custom backends", etc.)

👍🏽. I am going to separate them into different pages

@keewis,

I recall you mentioning that the xarray's sphinx build on RTD is configured to turn warnings into errors. Currently, I have an extension that warns that it's not safe for parallel reads. As a result, the entire build fails:

WARNING: the myst_nb extension is not safe for parallel reading WARNING: doing serial read

Can you suggest any workaround for this issue?

Thank you for the pointer to the matplolib's doc structure. I hadn't figured out the distinction between examples and tutorials until I looked at their examples (which seem to focus on a single feature) and tutorials (which seem to be a complete workflow with deep-dives) pages.

After looking at other projects, namely pymc3(https://docs.pymc.io/nb_tutorials/index.html, https://docs.pymc.io/nb_examples/index.html), scikit-learn (https://scikit-learn.org/stable/auto_examples/index.html, https://scikit-learn.org/stable/tutorial/index.html), I'm in favor of (1) having dedicated sections for both tutorials and examples and (2) merging the getting-started guide with user-guide.

So I wonder if it makes sense to move "Getting Started" under "User Guide" and add a new top-level "Tutorials"

@dcherian, I should point out that I created a new section (gallery) and this is where I've been putting the examples/tutorials. Are you suggesting that we merge the gallery, getting-started-guide with the user-guide? Or should we just - merge the getting-started with the user-guide and - then move the https://xray--4835.org.readthedocs.build/en/4835/index.html#see-also to the gallery section?

that's because of the headings in whats-new.rst. I think you have to be consistent with the style you use (=, +, ~, -).

Ah okay... ~~Is this issue connected to a specific sphinx version or readthedocs? I'm asking because I don't run into this issue locally~~

Edit: I was too quick to reply. 👍🏽 for @DocOtak's explanation (https://github.com/pydata/xarray/pull/4835#issuecomment-772729659)

Also, the build step also has a -W flag which turns warnings into Errors and causes a non 0 exit status. This is probably because the read the docs config file for xarray has a fail_on_warning set to true

Thank you for the clarification....

@pydata/xarray, does anyone know what's going on with readthedocs: https://readthedocs.org/projects/xray/builds/12928622/? I can't seem to figure out the error causing the build failures.

Cc @jhamman