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

docs: switch to Furo theme #1990

Merged
merged 5 commits into from
Jul 3, 2021
Merged

docs: switch to Furo theme #1990

merged 5 commits into from
Jul 3, 2021

Conversation

dgw
Copy link
Member

@dgw dgw commented Nov 15, 2020

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 use all lowercase). Seems fairly involved to fix (just setting add_help=False and making our own help args in add_common_arguments() created errors), but worth mentioning.

Checklist

  • I have read CONTRIBUTING.md
  • I can and do license this contribution under the EFLv2
  • No issues are reported by make qa (runs make quality and make test)
  • I have tested the functionality of the things this change touches

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.

@dgw dgw added this to the 8.0.0 milestone Nov 15, 2020
@dgw
Copy link
Member Author

dgw commented Feb 9, 2021

Fix for autoprogram is merged. Just awaiting a release now, then this should be really ready to drop very early in 8.0 dev.

@dgw
Copy link
Member Author

dgw commented Feb 11, 2021

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.

@dgw
Copy link
Member Author

dgw commented Jun 26, 2021

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.

dgw added 5 commits July 1, 2021 23:25
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()`.
@dgw dgw marked this pull request as ready for review July 2, 2021 05:02
@dgw dgw requested a review from a team July 2, 2021 05:03
@dgw dgw merged commit fc85888 into master Jul 3, 2021
@dgw dgw deleted the furo-docs branch July 3, 2021 05:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants