-
-
Notifications
You must be signed in to change notification settings - Fork 402
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
docs: switch to Furo theme #1990
Conversation
Fix for autoprogram is merged. Just awaiting a release now, then this should be really ready to drop very early in 8.0 dev. |
The autoprogram release that merged my indentation fix also dropped a ton of Python versions and added things like type annotations that absolutely will break on most of those old Python versions. Pretty ridiculous to make such major backward-incompatible changes in a patch release (0.1.5 -> 0.1.6), but not all projects are that careful about semver… So as expected, this project landed squarely in Sopel 8 territory. It's already labeled as such; I'm just confirming that it's there to stay, and briefly explaining why I don't want to deal with trying to pull it into 7.1. |
After #2062, this will be due for a refresh. Need to make sure the docs still build as expected under Sphinx 4 anyway, plus Furo just recently added support for the new major version of Sphinx itself. |
Furo brings a ton of face-lifting qualities to Sopel's documentation. Listing them all would be silly; one need only look at a Sphinx site generated with Alabaster alongside one generated with Furo to see. However, the most exciting improvements Furo brings are probably dark mode support, nicer autodoc layouts, and floating page contents (so it's harder to get lost in long pages full of many sections). To change themes, the following extra changes had to occur: * Furo's layout style does not work well with inline TOC display using `contents`, so those have been removed * A color-inverted version of Sopel's logo has been added for dark mode * Custom CSS to help Alabaster space out method/function descriptions has been replaced by (mostly) scrollbar enhancements Furo does not currently support `html_short_title` or a `description` one-line blurb about the project. Sopel's `description` option has been removed for now, since it wouldn't show anywhere, but hopefully we can put it back soon.
Bumped copyright year (only ~~six~~ eighteen months late, not bad), and killed off the `u` string prefixes that should've been removed when we dropped support for Python 2.
Bonus typo fix in `cli.utils.add_common_arguments()`.
Description
Alabaster is kind of stale, no? Furo is still "in beta", but Sopel's docs look great in it.
Dark mode support and a static page-outline sidebar are just a couple of the many improvements over Alabaster.
Known issues
No known issues with the theme itself. However, one thing that really bugs me now that I noticed it is the mixed capitalization between our own CLI arguments (which use
Sentence case
) and the auto-generated-h
/--help
options (which useall lowercase
). Seems fairly involved to fix (just settingadd_help=False
and making our own help args inadd_common_arguments()
created errors), but worth mentioning.Checklist
make qa
(runsmake quality
andmake test
)Notes
I started working on this intending to release this change with Sopel 8—but assuming that one little caveat with the description for
sopel-config list
can be solved, why not drop it with 7.1?Edit: Because
furo
won't install on py2 or py3.3, that's why.Edit: Some of this can be cherry-picked back to 7.1.2, though. Specifically, the added CLI help text, the fixed typo, and the updated copyright year.