DOC: Switch to pydata-sphinx-theme

[larsoner]

I hit a bug during doc build I thought was due to sphinx_rtd_theme, so I decided to try pydata-sphinx-theme to see if it would fix it. It didn't, but given that this simplifies our config a bit and matches what a bunch of other scientific packages are doing (numpy, scipy, matplotlib, scikit-learn, etc.) let's see if it looks good enough to keep. (Or really, seems like it's headed in a good enough direction to tweak a little bit more then merge!)

[GaelVaroquaux]

this given that this simplifies our config a bit and matches what a bunch of other scientific packages are doing (numpy, scipy, matplotlib, scikit-learn, etc.)

I think that we should maybe tweak it a tiny bit to have a distinguishable visual identity, but using it is definitely a good idea, because it will ensure that our css choices work well with what others are doing.

[lucyleeow]

Is it possible to add a left sidebar containing all sections?

https://pydata-sphinx-theme.readthedocs.io/en/v0.7.2/user_guide/configuring.html#configure-the-navigation-depth-and-collapsing-of-the-sidebar
Maybe with:

html_theme_options = {
  "navigation_depth": 2
}

?

[melissawm]

Hi folks - I checked this branch locally and managed to build the docs by pinning sphinx<6 - see pydata/pydata-sphinx-theme#1094

[larsoner]

Okay I got CIs happy and restructured things a bit to fit into the structure pydata-sphinx-theme prefers. I don't think this is perfect but I think it's good enough to merge and iterate on separately:

https://output.circle-artifacts.com/output/job/2fafe7f8-0fa1-496b-bb1b-3ce512240068/artifacts/0/rtd_html/index.html

I think that we should maybe tweak it a tiny bit to have a distinguishable visual identity,

For this I created an "icon" using an emoji, which is hopefully good enough until someone with more artistic skills can make a pass on the design :)

Good enough for now @lucyleeow @GaelVaroquaux ?

Also @melissawm since you showed some interest and got me working on this again :) -- if you have specific usability suggestions you'd like to push, feel free to make a PR based on my to my fork and I'll merge it there, then we can hopefully merge here!

[melissawm]

@larsoner thanks for the ping - I think this looks amazing, thanks for this 🚀

[choldgraf]

We'll get a new pydata-sphinx-theme release out soon I promise! If you like, try out the RC and provide feedback so we don't break something!

[larsoner]

@choldgraf the failure here seems like a bug in pydata-sphinx-theme:

WARNING: The version switcher "[https://sphinx-gallery.github.io/dev/_static/switcher.json"](https://sphinx-gallery.github.io/dev/_static/switcher.json%22) file cannot be read due to the following error:
HTTPError('404 Client Error: Not Found for url: https://sphinx-gallery.github.io/dev/_static/switcher.json')

note the extra ') at the end of the URL. This happens in our one Windows test, but in the Linux ones that use the same config. Do you test sphinx builds on Windows with a switcher.json over there?

[larsoner]

Argh wait no I think this is my error, let me confirm...

[larsoner]

All green! I'll merge this so we can start trying this out. Fingers crossed it doesn't cause any problems...

[larsoner]

Seems to be working

https://sphinx-gallery.github.io/dev/index.html

[GaelVaroquaux]

https://sphinx-gallery.github.io/dev/index.html

Nice! I must say that I have no love for the choice of colors in the dark mode of this theme (the light mode is fine, but the theme picks up the dark mode on my computer).

[GaelVaroquaux]