Skip to content

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

@ichard26

Description

@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

Metadata

Metadata

Assignees

Labels

S: needs discussionNeeds further hashing out before ready for implementation (on desirability, feasibility, etc.)T: documentationImprovements to the docs (e.g. new topic, correction, etc)

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions