Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Should we switch our Sphinx HTML theme away from Alabaster? #2397

Closed
ichard26 opened this issue Jul 24, 2021 · 10 comments · Fixed by #2793
Closed

Should we switch our Sphinx HTML theme away from Alabaster? #2397

ichard26 opened this issue Jul 24, 2021 · 10 comments · Fixed by #2793
Assignees
Labels
S: needs discussion Needs further hashing out before ready for implementation (on desirability, feasibility, etc.) T: documentation Improvements to the docs (e.g. new topic, correction, etc)

Comments

@ichard26
Copy link
Collaborator

ichard26 commented Jul 24, 2021

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 ichard26 added T: documentation Improvements to the docs (e.g. new topic, correction, etc) S: needs discussion Needs further hashing out before ready for implementation (on desirability, feasibility, etc.) labels Jul 24, 2021
@ichard26
Copy link
Collaborator Author

@JelleZijlstra
Copy link
Collaborator

JelleZijlstra commented Jul 24, 2021

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
Copy link
Contributor

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
Copy link
Collaborator Author

ichard26 commented Dec 27, 2021

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
Copy link
Contributor

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

@felix-hilden
Copy link
Collaborator

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
Copy link
Collaborator

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

@ichard26 ichard26 self-assigned this Jan 21, 2022
@ichard26
Copy link
Collaborator Author

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

@ichard26
Copy link
Collaborator Author

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)

@ichard26
Copy link
Collaborator Author

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

Thanks for all of your great work on Furo!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
S: needs discussion Needs further hashing out before ready for implementation (on desirability, feasibility, etc.) T: documentation Improvements to the docs (e.g. new topic, correction, etc)
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants