Skip to content

DOC: Add theme switcher and default to lightmode. #414

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.

Sign up for GitHub

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

Merged
merged 4 commits into from
Jul 7, 2022
Merged

DOC: Add theme switcher and default to lightmode. #414

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e871cdf
DOC: Add theme switcher and default to lightmode.
rossbar Jul 6, 2022
a194b5b
Make linter happy.
rossbar Jul 6, 2022
26caf95
Add workaround for theme versions that don't support mode switcher.
rossbar Jul 6, 2022
7d109d4
Add comment about theme version checking in conf.
rossbar Jul 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,26 @@
"show_prev_next": False,
"navbar_end": ["search-field.html", "navbar-icon-links.html"],
}
# NOTE: The following is required for supporting of older sphinx toolchains.
# The "theme-switcher" templated should be added directly to navbar_end
# above and the following lines removed when the minimum supported
# version of pydata_sphinx_theme is 0.9.0
# Add version switcher for versions of pydata_sphinx_theme that support it
import packaging
import pydata_sphinx_theme

if packaging.version.parse(pydata_sphinx_theme.__version__) >= packaging.version.parse(
"0.9.0"
):
Comment on lines +96 to +98
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is the conf.py for our own docs (i.e., won't affect end users, just our own internal doc builds + deployment), so I'd rather just require 0.9.0+ from now on. WDYT?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The problem is (I think) we use the doc build in CI as an extra set of testing, which is why I did the pinning (annoyingly) in the doc conf.

I'll try just pinning in the doc requirements - if that doesn't require a bunch of CI overhaul then I'll stick with that!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, the failing CI confirms my suspicions. The potential solutions that come to mind are:

  1. Handle the pinning/version checking dynamically in the conf.py as 26caf95 does
  2. Remove the jobs that build the documentation as part of the tests in CI

Other ideas? Of those two, I prefer the first as doc builds in CI can in principle help catch issues that are not explicitly covered by unit tests.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah the way you had it before is fine, I forgot about needing to stay compatible with older Sphinx etc.

html_theme_options["navbar_end"].insert(0, "theme-switcher")


html_sidebars = {
"**": [],
}
html_context = {
"default_mode": "light",
}

html_title = f"{project} v{version} Manual"
html_last_updated_fmt = "%b %d, %Y"
Expand Down