Skip to content

docs: Use PyData Sphinx Theme version switcher#2694

Open
kratsg wants to merge 2 commits intomainfrom
docs/version-switcher
Open

docs: Use PyData Sphinx Theme version switcher#2694
kratsg wants to merge 2 commits intomainfrom
docs/version-switcher

Conversation

@kratsg
Copy link
Copy Markdown
Contributor

@kratsg kratsg commented Apr 11, 2026

Pull Request Description

Use the PyData Sphinx Theme version switcher and version warning banner instead of the custom hand-rolled solution currently in the docs.

Closes #2516.

Checklist Before Requesting Reviewer

  • Tests are passing
  • "WIP" removed from the title of the pull request
  • Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

  • Summarize commit messages into a comprehensive review of the PR

* Add `docs/_static/switcher.json` with all stable releases mapping versions
  to their ReadTheDocs URLs.
* Configure `html_theme_options` in `docs/conf.py` to enable the PyData
  Sphinx Theme version switcher and version warning banner, using
  `READTHEDOCS_VERSION` to set `version_match` at build time.
* Remove the hand-rolled dev-version warning banner (raw HTML in
  `index.rst` and `citations.rst`, JS detection in `custom.js`, and
  CSS in `custom.css`) now that `show_version_warning_banner` from the
  PyData Sphinx Theme covers the same use case.
* Exempt `docs/_static/switcher.json` from the `docs/_*/` gitignore rule.

@kratsg kratsg self-assigned this Apr 11, 2026
@kratsg kratsg requested a review from matthewfeickert April 11, 2026 02:44
@kratsg kratsg added the docs Documentation related label Apr 11, 2026
@github-project-automation github-project-automation bot moved this to In progress in pyhf v0.8.0 Apr 11, 2026
@codecov
Copy link
Copy Markdown

codecov bot commented Apr 11, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.28%. Comparing base (24b1013) to head (e631adc).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #2694   +/-   ##
=======================================
  Coverage   98.28%   98.28%           
=======================================
  Files          65       65           
  Lines        4305     4305           
  Branches      465      465           
=======================================
  Hits         4231     4231           
  Misses         46       46           
  Partials       28       28           
Flag Coverage Δ
contrib 98.16% <ø> (ø)
doctest 98.28% <ø> (ø)
unittests-3.10 96.46% <ø> (ø)
unittests-3.11 96.46% <ø> (ø)
unittests-3.12 96.46% <ø> (ø)
unittests-3.13 96.46% <ø> (ø)
unittests-3.9 96.53% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@kratsg kratsg force-pushed the docs/version-switcher branch from 34a56f8 to 7a01ca2 Compare April 11, 2026 06:22
kratsg and others added 2 commits April 11, 2026 15:49
Adds the switcher.json with all stable releases and configures
html_theme_options to use the PyData version switcher widget and
version warning banner (shown when browsing non-stable docs).

Closes #2516

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Remove the hand-rolled dev-version warning (raw HTML in index.rst and
citations.rst, JS detection in custom.js, and CSS in custom.css) now
that show_version_warning_banner from PyData Sphinx Theme covers the
same use case. Also exempt switcher.json from the docs/_*/ gitignore
rule so force-add is not needed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@kratsg kratsg force-pushed the docs/version-switcher branch from 7a01ca2 to e631adc Compare April 11, 2026 13:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation related

Projects

Status: In progress

Development

Successfully merging this pull request may close these issues.

Use PyData Sphinx Theme docs version switcher

1 participant