Switch documentation to pydata-sphinx-theme

[TomNicholas]

• Closes Why did you go to the sphinx-book-theme instead of the pydata-sphinx-theme ? #8701, Docs sidebar is squished #8619 site menu of documentation obstructing view on mobile #8366, Table of contents overlapping content #10223
• User visible changes (including notable bug fixes) are documented in whats-new.rst

How might we want to move headers/sections around to take advantage of now having a navigation bar at the top? Adding an explicit link to the tutorial.xarray.dev site would be good.

PR Docs Preview Link for convenience: https://xray--8708.org.readthedocs.build/en/8708/

[TomNicholas]

Docs build failed because we fail on warnings:

preparing documents... WARNING: unsupported theme option 'repository_url' given
WARNING: unsupported theme option 'repository_branch' given
WARNING: unsupported theme option 'path_to_docs' given
WARNING: unsupported theme option 'use_repository_button' given
WARNING: unsupported theme option 'use_issues_button' given
WARNING: unsupported theme option 'home_page_in_toc' given
WARNING: unsupported theme option 'extra_footer' given

[scottyhq]

I just came across this trying to sort out #10223! Experimenting locally, that issue seems fixed by simply gutting the custom style file https://github.com/pydata/xarray/blob/main/doc/_static/style.css in favor of relying on newer theme defaults

However, it seems probably a good time to also update the theme since executable_book_theme is not seeing as much development (xref https://executablebooks.org/en/latest/blog/2024-05-20-jupyter-book-myst/#what-this-means-for-jupyter-book-v1-users) as pydata_sphinx_theme (which it explicitly pins):
https://github.com/executablebooks/sphinx-book-theme/blob/23f6936ae956428463f2ec97eebc2fe68bdd344b/pyproject.toml#L40

Ok if I just take over this PR? Or should I start a fresh one?

[TomNicholas]

Do as you see fit @scottyhq !

FYI I think there are other discussion about the much more radical idea of using MyST for the docs. But that would be a big project...

[scottyhq]

I believe most of this is making adjustments to the previous theme, and I found that simply removing most of it does fix #10223 (the issue of strange sidebar behavior with varying theme size). You can see that is remedied by making this browser window narrower https://xray--8708.org.readthedocs.build/en/8708/getting-started-guide/quick-overview.html

[scottyhq]

Took me an annoying long time to figure out that decreasing the indention on these solved the following sphinx/autodoc warnings:

/Users/scotthenderson/GitHub/xarray/xarray/xarray/plot/accessor.py:docstring of xarray.plot.accessor.DatasetPlotAccessor.quiver:7: CRITICAL: Unexpected section title.

Parameters
----------
xarray/plot/accessor.py:docstring of xarray.plot.accessor.DatasetPlotAccessor.quiver:11: ERROR: Unexpected indentation.
xarray/plot/accessor.py:docstring of xarray.plot.accessor.DatasetPlotAccessor.quiver:12: WARNING: Block quote ends without a blank line; unexpected unindent.
xarray/plot/accessor.py:docstring of xarray.plot.accessor.DatasetPlotAccessor.quiver:117: WARNING: Inline strong start-string without end-string.

[scottyhq]

OK, RTD is happy and I think this is looking pretty good. Would be great for others to review the preview, given the look and feel is different, albeit pretty similar to the past!

https://xray--8708.org.readthedocs.build/en/8708/

How might we want to move headers/sections around to take advantage of now having a navigation bar at the top?

I didn't adjust this, and it is a fairly significant change. (Edit: now modified). There is no longer a left-side primary sidebar with categorized sections on the landing page, instead currently all the TOC links listed in the index end up in the top bar https://github.com/pydata/xarray/blob/main/doc/index.rst. It is possible to configure how many links are on the top bar before the 'More' dropdown https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/header-links.html#navigation-bar-dropdown-links

[dcherian]

Very nice! Thanks @scottyhq

The API reference navigation is a weird: https://xray--8708.org.readthedocs.build/en/8708/api.html . Seems like what's on the right should be on the left.

[dcherian]

This is also probably a good time to change the top-level "tutorials link" to link to https://tutorial.xarray.dev

[scottyhq]

The API reference navigation is a weird: https://xray--8708.org.readthedocs.build/en/8708/api.html . Seems like what's on the right should be on the left.

I thought that initially too. But it's essentially how the current docs are structured (https://docs.xarray.dev/en/v2025.03.1/api.html), it's just that the current docs have the persistent left-hand sidebar to navigate the entire site.

Seems possible to do more "section" subdivisions though to accomplish this, for example, see the Pandas API landing page:
https://pandas.pydata.org/docs/reference/index.html

[scottyhq]

How might we want to move headers/sections around to take advantage of now having a navigation bar at the top?

I wanted to add a bit more discussion and a concrete proposal for this. I think given the restructured theme it would be good to tweak the existing structure before merging this (just re-organize, not rewriting). To begin, here is a quick survey of "top bars":

Pandas:

Getting started - User Guide - API reference - Development - Release notes

Scipy:

Installing - User Guide - API reference - Building from source - Development - Release notes

Numpy:

User Guide - API reference - Building from source - Development - Release notes - Learn

More.. NEPS

Scikit-learn:

Install - User Guide - API - Examples - Community

More… getting_started - whats_new - Glossary - Development - FAQ - support - related_projects - roadmap - Governance - about

matplotlib:

Plot types - User guide - Tutorials - Examples - Reference - Contribute

Xarray this PR:

Getting Started - User Guide - Gallery - Tutorials & Videos - API Reference

More.. How do I .. - Getting Help - Ecosystem - Contributing Guide - Xarray Internals - Development Roadmap - Team - Developers Meeting - What’s New - GitHub repository - GitHub discussions - StackOverflow

---

Proposal: Keep 4-6 main categories only in top bar, move the rest under respective sections:

Getting Started - User Guide - API Reference - Developer Guide

Developer Guide -> Contributing Guide, Xarray Internals, Development Roadmap, Developers Meeting, Team, What’s New

User Guide -> Gallery, Tutorials & Videos, How do I…, Getting Help, Ecosystem, Discussions, StackOverflow

After writing this out I thought it could be nice to keep the ‘Gallery’ and ‘Getting Help’ as their own sections in the top bar… Obviously many ways to do it, but I think keeping the main sections to a minimum (<6) is appealing. Thoughts? Also pinging @andrewendlinger because I saw you had some nice suggestions in #10236 and your perspective would be appreciated!

[dcherian]

I like your "Developer Guide" top-level though perhaps call it "Contribute" (low-confidence suggestion).

Getting Help - How do I - GitHub repository - GitHub discussions - StackOverflow

These could be under the "Getting Help" (or even "Help") top-level heading (which is currently just one page. I think it's nice to surface this as top-level instead of expecting people to click in to User Guide to find it.

[andrewendlinger]

Thanks for including me :) The new structure design is great!

I agree, the current pile up inside "More" is probably too much / redundant.

Also, since the Tutorials website is so neat, I would keep it at the top for a dedicated shout out.

So something like that?

---

Getting Started	User Guide	Tutorials	Gallery	API Reference	Contribute

• Getting Started

  • Overview: Why xarray?
  • Installation
  • xarray Quick Start (former 'quick overview')
  • Getting Started Tutorials (links to tutorials)
  • Getting Help
    • Getting Help
    • FAQ
    • Community (stackoverflow, discussions etc.)

• User Guide

  • *All the user guide chapters (ideally with substructure such as in Docs: User Guide Landing Page #10236)
  • How do I....
  • Ecosystem

• Tutorials

  • Forwards to https://tutorial.xarray.dev/

• Gallery

• API Reference

• Contribute

  • Contributing Guide
  • Xarray Internals
  • Development Roadmap
  • Developers Meeting
  • Team
  • What’s New

Btw, https://matplotlib.org also has a nice structure.

[scottyhq]

It was really quite straightforward to do this, and the resulting quickstart page in my opinion looks a lot more inviting for new users! I'd be happy to fully convert the other docs in a separate PR if people like it.

[scottyhq]

https://xray--8708.org.readthedocs.build/en/8708/getting-started-guide/quick-overview.html
vs
https://docs.xarray.dev/en/stable/getting-started-guide/quick-overview.html

note: except if 'dark mode' on the theme is set, I opened pydata/pydata-sphinx-theme#2189 to sort that out

[andrewendlinger]

The html output instead of the raw string is amazing!

[benbovy]

I haven't been looking at the changes here in depth, but from quick inspection of the rendered docs this looks great! (at least in light mode for now).

Two comments:

• The release notes (what's new) page is hardly reachable / discoverable via "Contribute". In all other projects referenced above (pandas, numpy, scipy and matplotlib) there's a direct link in the top bar of their documentation.

• It's out of scope of this PR and may be addressed later, but IMO the "Contribute > Xarray internals" section could be reworked as currently it looks a bit like a catch-all section. More specifically, the pages about extending Xarray (accessors, IO backends, indexes...) could be more visible too. Perhaps move these into a new "Advanced Guide" or "Extending Xarray" top-level section? Technically those pages can be viewed as "contributing" to the Xarray ecosystem, but I rather view the "Contribute" section (and "Xarray internals") as helping to contribute to Xarray itself.

[benbovy]

The only social link shown in the top bar is twitter. I'd be in favor of either add other social links like https://bsky.app/profile/xarray.bsky.social (maybe the Xarray-dev Discord server as well?) there, or only keep the github link to avoid cluttering the top bar (and add all social links elsewhere).

[scottyhq]

The release notes (what's new) page is hardly reachable / discoverable via "Contribute".

I agree that often-visited pages should be easy to reach! In general I think it's good to mimic but not copy the other major libraries. I view the top bar more as 'category' subsections each having many pages, rather than links to a specific page.W
While I don't have a strong preference either way, what about putting a link in the 'Useful links' instead? Could probably remove 'Mailing List' there as it's not really used much anymore? (Also the top bar collapses on small screens):

It's out of scope of this PR and may be addressed later, but IMO the "Contribute > Xarray internals" section could be reworked as currently it looks a bit like a catch-all section.

Agreed! I'd be happy to tackle more re-org to that section as well as the API section as separate stand-alone PRs. I found that I was needing to restrain myself from too many changes... it's easy to get a bit carried away with a docs refresh :)

I'd be in favor of either add other social links like https://bsky.app/profile/xarray.bsky.social (maybe the Xarray-dev Discord server as well?) there, or only keep the github link to avoid cluttering the top bar (and add all social links elsewhere).

Yeah, I don't use these much, so am in favor of just the GitHub link

[benbovy]

Personally it often frustrates me when I can't quickly navigate to the release notes of any library in general, but I'm curious about others opinion on this! From what I see, the "release notes" page often gets special treatment at the same level as the top-level categories (for a good reason IMO). It could be linked as well in "Useful Links" (duplicate links are good), or like in astropy right next to the version number.

[scottyhq]

From what I see, the "release notes" page often gets special treatment at the same level as the top-level categories (for a good reason IMO). It could be linked as well in "Useful Links" (duplicate links are good), or like in astropy right next to the version number.

Sounds good. Also, I liked the astropy approach of linking next to the version number! So I changed both and added a separate social media page. I'm pretty happy with this as-is now, but of course open to other modifications. After merging this one I think it'd be great to improve upon different sections one at a time (@andrewendlinger, I did not implement all your suggestions, but I think they are great so a separate PR would be very welcome).

[dcherian]

This is a great step forward!