Should we switch our Sphinx HTML theme away from Alabaster?

[ichard26]

As far as I know, Black has stuck with the same old theme from day one. I'll admit it's nice and fits in nicely with the more rustic / old vibe the all of the branding has (eg. Ford-like logo, name based off quote that's quite old). Unfortunately there's a few hard-to-workaround issues:

• Phones or really any devices with small screens are not supported at all
• Due to limitations (ie. no scrolling support in the sidebar), there's custom CSS, see /docs/_static/custom.css - now I'm no web dev and I'm not sure if anyone else on the maintainer team is ... so if anything goes wrong we could easily become screwed

Also in general the theme is less friendly towards certain structural layouts (the TOCs are quite limiting - makes content hard to navigate if you aren't careful). It's not a big deal now and hopefully ever (redesigns are tiring and cause a lot of churn) but at least having the option is nice. Oh and not to mention that Alabaster seems to be lacking attention.

The main alternatives I know of are Furo and ReadTheDocs.

But this is a big noticeable change and does touch the concept of project branding which I've tried to avoid as much as possible since I've joined (never felt like I held enough authority to bring it up). Hopefully the discussion is worthwhile even if the answer is "no, we aren't changing it" :)

edit: I'll provide previews for the two alternatives I mentioned, sadly I just thought of this idea after posting this so gimme a moment

[ichard26]

Previews:

• Furo: https://black.readthedocs.io/en/hello-furo/
• ReadTheDocs theme: https://black.readthedocs.io/en/hello-rtd-theme/

[JelleZijlstra]

Thanks for putting this together! The Furo theme looks a bit better to me. Concretely, I like that the chevrons for expanding a section are clearly visible; RTD has "+" for that instead which is almost impossible to see.

[johnthagen]

As a bystander, I personally think furo is the best Sphinx theme I've come across. It will also respect the browser's preference for dark mode and show a dark theme if that is the user's preference.

[ichard26]

FWIW I find Furo to be easier to navigate than ReadTheDocs, those + are pretty unreadable and small (especially annoying on mobile) so I'll put my hat in for Furo as well. The light/dark mode switch feature is a nice touch especially as the project is named "black" haha.

[Shivansh-007]

The stable release is coming close, we could use this as an opportunity to introduce some brand new looking docs.

[felix-hilden]

Personally I use RTD, but I hate how the logo looks on the blue background. Along with the other points raised here, let's go Furo.

[JelleZijlstra]

Let's go with Furo. I'd be happy to review and merge a PR implementing it.

[ichard26]

Alright, I'll port over my old branch to current main later today then.

[ichard26]

I plan to delete the branches the previews are based off and that might break the links. For historical record, here's the source commits for both previews (feel free to checkout and build 'em locally)

• Furo: 6ba030e
• ReadTheDocs: 4c5c515

[ichard26]

Wheee congrats @pradyunsg your theme has conquered another major Python project 🎉

Thanks for all of your great work on Furo!