diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 3dbab63838..9c5176131b 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -14,6 +14,15 @@ build:
- curl
- jq
jobs:
+ post_checkout:
+ # Read the Docs clones with --depth 50 and without tags, so hatch-vcs cannot find
+ # the release tag and falls back to a "0.1.dev50" version. That is what reaches
+ # the docs as Sphinx's ``version`` and ``release``, so without this the published
+ # documentation for a release reports itself as 0.1.dev50.
+ #
+ # --unshallow errors on an already complete clone, so fall back to fetching the
+ # tags alone rather than ignoring every failure.
+ - git fetch --tags --unshallow || git fetch --tags
post_create_environment:
- pip install uv
post_install:
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
deleted file mode 100644
index 19972cd849..0000000000
--- a/docs/_static/css/custom.css
+++ /dev/null
@@ -1,46 +0,0 @@
-/* 1200px for slightly wider for most monitors */
-.wy-nav-content {
- max-width: 1200px !important;
-}
-
-/* version warning badge */
-#dev-version {
- display: none;
-}
-
-#dev-version.version-warning {
- display: block;
-}
-
-p.version-warning {
- position: sticky;
- top: 10px;
-
- margin: 10px 0;
- padding: 5px 10px;
- border-radius: 4px;
-
- letter-spacing: 1px;
- color: #fff;
- text-shadow: 0 0 2px #000;
- text-align: center;
-
- background: #900 repeating-linear-gradient(
- 135deg,
- transparent,
- transparent 56px,
- rgba(255, 255, 255, 0.35) 56px,
- rgba(255, 255, 255, 0.35) 112px
- );
-}
-
-p.version-warning a {
- color: #fff;
- text-decoration: none;
- border-bottom: 1px dotted #fff;
-}
-
-p.version-warning a:hover {
- border-bottom-style: solid;
-}
-/* -------------------------- */
diff --git a/docs/_static/js/custom.js b/docs/_static/js/custom.js
deleted file mode 100644
index 1060f4663e..0000000000
--- a/docs/_static/js/custom.js
+++ /dev/null
@@ -1,9 +0,0 @@
-document.addEventListener("DOMContentLoaded", function() {
- let dev_version = document.getElementById("dev-version");
- let on_scikit_hep = window.location.href.indexOf("scikit-hep.org/pyhf") > -1;
-
- if(dev_version && on_scikit_hep){
- // are we not on readthedocs?
- dev_version.classList.add("version-warning");
- }
-});
diff --git a/docs/citations.rst b/docs/citations.rst
index dd5471ab46..ce82869c32 100644
--- a/docs/citations.rst
+++ b/docs/citations.rst
@@ -1,9 +1,12 @@
Use and Citations
=================
-.. raw:: html
+.. ifconfig:: is_development_build
- Warning: This is a development version and should not be cited. To find the specific version to cite, please go to ReadTheDocs.
+ .. warning::
+
+ This is a development version and should not be cited. To find the specific
+ version to cite, please go to `ReadTheDocs `__.
Citation
--------
diff --git a/docs/conf.py b/docs/conf.py
index a34d1a9805..ba52c69a3a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -16,6 +16,7 @@
# documentation root, use Path('../relative_path_to_dir').resolve() to make it absolute, like shown here.
import importlib.metadata
+import os
import sys
from pathlib import Path
@@ -36,6 +37,7 @@ def setup(app):
app.add_css_file(
"https://cdnjs.cloudflare.com/ajax/libs/github-fork-ribbon-css/0.2.2/gh-fork-ribbon.min.css"
)
+ app.add_config_value("is_development_build", default=False, rebuild="env")
# -- General configuration ------------------------------------------------
@@ -240,11 +242,38 @@ def setup(app):
#
html_theme = "pydata_sphinx_theme"
+# Read the Docs provides its own version switcher, so these docs do not need one, but
+# its notification addon renders nothing, so the development version still has to say
+# so for itself. That covers the GitHub Pages deployment and local builds, neither of
+# which is on Read the Docs, along with Read the Docs' own "latest" and its pull
+# request previews, which set READTHEDOCS_VERSION to the pull request number. Builds of
+# "stable" and of a release tag say nothing.
+#
+# The theme's own 'show_version_warning_banner' cannot be used for this, as it is only
+# rendered when a version switcher 'json_url' is configured.
+is_development_build = (
+ os.environ.get("READTHEDOCS") != "True"
+ or os.environ.get("READTHEDOCS_VERSION") == "latest"
+ or os.environ.get("READTHEDOCS_VERSION_TYPE") == "external"
+)
+
+_announcement = (
+ "This is a development version. The latest stable version is at "
+ 'pyhf.readthedocs.io.'
+ if is_development_build
+ else ""
+)
+
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
-html_theme_options = {"header_links_before_dropdown": 6}
+html_theme_options = {
+ "header_links_before_dropdown": 6,
+ # c.f. https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/announcements.html
+ "announcement": _announcement,
+ "sticky_banners": True,
+}
# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = []
@@ -274,12 +303,7 @@ def setup(app):
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ["_static"]
-html_css_files = [
- "css/custom.css",
-]
-
html_js_files = [
- "js/custom.js",
(
"https://views.scientific-python.org/js/plausible.js",
{"data-domain": "pyhf.readthedocs.io", "defer": "defer"},
diff --git a/docs/index.rst b/docs/index.rst
index 7bddc7b269..57d9015887 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -22,10 +22,6 @@
release-notes
contributors
-.. raw:: html
-
- Warning: This is a development version. The latest stable version is at ReadTheDocs.
-
..
Comment: Splice the JupyterLite example into the README by looking for a particular comment