issue_comments

Thank you @keewis, @dcherian, @shoyer!

+1

On Mon, Mar 15, 2021 at 6:18 AM Anderson Banihirwe @.***> wrote:

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

— You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub https://github.com/pydata/xarray/pull/4835#issuecomment-799412180, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJJFVX555NNH4KALUDP22TTDYCK3ANCNFSM4WMDZXNA .

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.

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

You could try to reduce the (quite big) margin on the left / right

@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.

@andersy005, the copy button feature is a great find, copying examples is so much easier than before.

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).

Anderson, I like the RTD-like sidebar. I think every pydata user is conditioned to look at the left sidebar to navigate the documentation :) so preserving it is nice.

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

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

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

In general, this is very awesome. I think we should merge soon and iterate further.

@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

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 don't know any, unfortunately. We do want to keep the warnings-as-errors because those tend to result in broken page layouts, but RTD insists on the parallel build (which does make the builds faster) and myst-nb doesn't seem to support it. Is there a particular reason why we're moving away from nbsphinx?

@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.

The tutorial/video resources are a bit hidden right now. It would be good to emphasize them somehow.

For e.g. matplotlib has (https://matplotlib.org/) Installation Documentation Examples Tutorials Contributing in their top bar, so my suggestion was to add Tutorials in the top bar. That would make the top bar a bit crowded which is why I suggested merging getting-started with the user-guide.

Let's wait for some more opinions before making changes.

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?

Anderson, this newest version looks really great.

I noticed that https://xray--4835.org.readthedocs.build/en/4835/index.html#see-also is really a list of tutorials and talks, which would be nice to highlight.

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

the build step also has a -W flag which turns warnings into Errors and causes a non 0 exit status

this is intentional: these errors usually cause the page layout to break somehow, so failing the sphinx build (especially in PRs) is important. We also try to minimize the nitpicky errors, but we don't enforce that since it seems almost impossible to silence all of them (we inherit docstrings from other projects like numpy, pandas, and matplotlib), and they only result in broken links.

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....

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

@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