docs: Use PyData Sphinx Theme version switcher

[kratsg]

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.

Summary by CodeRabbit

• Documentation

  • Added version switcher to enable selecting between different documentation versions.
  • Removed development version warning messages from documentation pages.

• Style

  • Updated documentation navigation layout constraints.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.28%. Comparing base (2d265a2) to head (65f6462).

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.

[coderabbitai]

Warning

Rate limit exceeded

@matthewfeickert has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 49 minutes and 38 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 07a84eb3-f22d-4d71-af12-4843dc6cc222

📥 Commits

Reviewing files that changed from the base of the PR and between de9662b and 65f6462.

📒 Files selected for processing (1)

• docs/_static/switcher.json

📝 Walkthrough

Walkthrough

This PR migrates the pyhf documentation from a custom version warning and switcher implementation to the PyData Sphinx Theme's built-in version switcher. The theme configuration is updated to reference a version switcher JSON file, obsolete custom JavaScript logic and CSS styling are removed, and hardcoded development-version warnings are deleted from documentation pages.

Changes

Version Switcher Configuration

Layer / File(s)	Summary
Theme version switcher configuration docs/conf.py, docs/_static/switcher.json, .gitignore	Import os and configure html_theme_options with version switcher JSON URL and version_match sourced from READTHEDOCS_VERSION environment variable. Add docs/_static/switcher.json defining version entries (development "latest" and historical releases with name, version, and URL). Add .gitignore rule to exclude switcher.json from version control.
Remove custom version warning implementation docs/_static/js/custom.js, docs/_static/css/custom.css, docs/index.rst, docs/citations.rst	Remove the DOMContentLoaded event handler that conditionally applied version-warning class. Remove version-warning badge CSS styling and add .wy-nav-content max-width constraint. Remove hardcoded development-version warning blocks from index and citations pages.

---

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: replacing the custom documentation version switcher with PyData Sphinx Theme's built-in version switcher.
Linked Issues check	✅ Passed	The PR successfully implements all primary objectives from issue #2516: adds switcher.json with version mappings, configures html_theme_options for the PyData version switcher and warning banner, removes custom dev-version warnings, and exempts switcher.json from gitignore.
Out of Scope Changes check	✅ Passed	All changes are directly related to the stated objective of migrating to PyData Sphinx Theme version switcher; no unrelated modifications detected across modified files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[matthewfeickert]

One minor fix.

[matthewfeickert]

@kratsg one comment / suggested change that I want your approval on, but then this is good to do.

[matthewfeickert]

@kratsg comparing with https://github.com/pydata/pydata-sphinx-theme/blob/d17eb2e1b7438164b92d40b947e01813a105fac3/docs/_static/switcher.json#L6-L21 as an example and noting from https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/announcements.html#version-warning-banners

This functionality relies on the version switcher to determine the version number of the latest stable release. It will only work if your version switcher .json has exactly one entry with property "preferred": true and your entries have version properties that are parsable by the compare-versions node module
...
If the active version compares less than the preferred version, the announcement will inform the user that they are viewing an older version of the documentation and provide a link to the preferred version. If the version compares greater than the preferred version (or if the version match contains the strings “dev”, “rc” or “pre”), the announcement will say they are viewing an unstable development version instead.

then I think we need to remove 0.7.6 to keep the version switcher from viewing 0.7.6 as somehow "older" than the stable version.

Suggested change

	{
	"name": "v0.7.6",
	"version": "v0.7.6",
	"url": "https://pyhf.readthedocs.io/en/v0.7.6/"
	},

[matthewfeickert]

but then this is good to do.

Hm. We might need more work though as the ReadTheDocs build (and locally for me) isn't rendering any dropdown menu correctly. There is just an empty box where the options should be.