From 8add5183adaee961712fd7c3c5dc01230c401a64 Mon Sep 17 00:00:00 2001 From: Clement Tsang <34804052+ClementTsang@users.noreply.github.com> Date: Fri, 26 Dec 2025 00:58:11 -0500 Subject: [PATCH] docs: add banner for nightly version (#1931) * docs: try and add notification for nightly version * hmmm * hmmmm * I forgot to run the banner * fix spacing * some more comments * fmt --- .github/workflows/post_release.yml | 5 ++--- docs/content/overrides/main.html | 1 - docs/hooks/nightly_banner.py | 17 +++++++++++++++++ docs/hooks/nightly_redirect.py | 15 +++++++++++---- docs/mike.sh | 25 +++++++++++++++++++++++++ docs/mkdocs.yml | 10 ++++++++-- docs/overrides/main.html | 10 ++++++++++ 7 files changed, 73 insertions(+), 10 deletions(-) delete mode 100644 docs/content/overrides/main.html create mode 100644 docs/hooks/nightly_banner.py create mode 100755 docs/mike.sh create mode 100644 docs/overrides/main.html diff --git a/.github/workflows/post_release.yml b/.github/workflows/post_release.yml index e1a36555..dafe3e21 100644 --- a/.github/workflows/post_release.yml +++ b/.github/workflows/post_release.yml @@ -70,14 +70,13 @@ jobs: run: ./scripts/ci/configure_git.sh # TODO: Test this with the script instead + # TODO: We no longer need the renaming logic after the next release! - name: Build and deploy docs with mike as the latest stable branch run: | cd docs - OLD_STABLE_VERSION=$(mike list stable | grep -Po '([0-9]+.[0-9]+.[0-9]+)' | head -n1) + OLD_STABLE_VERSION=$(mike list stable | grep -Po '(\d{1,3}\.\d{1,3}\.\d{1,3})' | head -n1) echo ${OLD_STABLE_VERSION} mike retitle --push stable ${OLD_STABLE_VERSION} - mike deploy --push --update-aliases ${RELEASE_VERSION} stable - mike retitle --push ${RELEASE_VERSION} "${RELEASE_VERSION} (stable)" chocolatey: needs: [initialize] diff --git a/docs/content/overrides/main.html b/docs/content/overrides/main.html deleted file mode 100644 index 94d9808c..00000000 --- a/docs/content/overrides/main.html +++ /dev/null @@ -1 +0,0 @@ -{% extends "base.html" %} diff --git a/docs/hooks/nightly_banner.py b/docs/hooks/nightly_banner.py new file mode 100644 index 00000000..e0489e5a --- /dev/null +++ b/docs/hooks/nightly_banner.py @@ -0,0 +1,17 @@ +import os +import sys + +import mkdocs.plugins + + +@mkdocs.plugins.event_priority(-100) +def on_config(config): + print("Running nightly banner hook...", file=sys.stderr) + + # From https://github.com/jimporter/mike/blob/3351d5feabff8ee107f4ad6d1f86055843c7dbf1/mike/mkdocs_utils.py#L13 + version = os.environ.get("MIKE_DOCS_VERSION") + print(f"Version: {version}", file=sys.stderr) + + if version == "nightly": + extra = config.get("extra", {}) + extra["nightly"] = True diff --git a/docs/hooks/nightly_redirect.py b/docs/hooks/nightly_redirect.py index 00c55d7a..5327c8ae 100644 --- a/docs/hooks/nightly_redirect.py +++ b/docs/hooks/nightly_redirect.py @@ -1,7 +1,8 @@ import os +import sys +import json import mkdocs.plugins import urllib.request -import json # Based on https://github.com/squidfunk/mkdocs-material/discussions/3758#discussioncomment-4397373 @@ -9,7 +10,7 @@ import json @mkdocs.plugins.event_priority(-50) def on_config(config): - print("Running nightly release redirect hook...") + print("Running nightly release redirect hook...", file=sys.stderr) try: nightly_tag_name = None override = os.environ.get("MKDOCS_NIGHTLY_RELEASE_OVERRIDE") @@ -35,8 +36,14 @@ def on_config(config): redirects = redirect_plugin.config.get("redirect_maps", {}) redirects["nightly-release.md"] = nightly_release_url - print(f"Updated nightly release redirect to point to {nightly_release_url}") + print( + f"Updated nightly release redirect to point to {nightly_release_url}", + file=sys.stderr, + ) else: print("nightly tag name was not set by any means.") except Exception as e: - print(f"error adjusting redirect, falling back to general releases page: {e}") + print( + f"error adjusting redirect, falling back to general releases page: {e}", + file=sys.stderr, + ) diff --git a/docs/mike.sh b/docs/mike.sh new file mode 100755 index 00000000..7ddf6256 --- /dev/null +++ b/docs/mike.sh @@ -0,0 +1,25 @@ +#!/bin/bash + +# Used to serve a versioned version of the docs locally. Note this +# does NOT reflect local changes. + +set -e + +VENV_PATH="./.venv/" +PYTHON_CMD=${1:-python} + +if [ ! -d $VENV_PATH ]; then + echo "venv not found, creating one using the command '${PYTHON_CMD}'..."; + $PYTHON_CMD -m venv .venv; + source $VENV_PATH/bin/activate; + pip install --upgrade pip; + pip install -r requirements.txt; + $VENV_PATH/bin/mike serve; +else + echo "venv already found."; + source $VENV_PATH/bin/activate; + pip install --upgrade pip; + pip install -r requirements.txt; + $VENV_PATH/bin/mike serve; +fi; + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index ba49a49e..626ef46d 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -54,7 +54,7 @@ theme: toggle: icon: material/weather-night name: Switch to system preference - custom_dir: "content/overrides" + custom_dir: "overrides" extra_css: - stylesheets/extra.css @@ -147,6 +147,8 @@ extra: provider: mike default: stable alias: true + # Used for the nightly banner + nightly: false # Navigation nav: @@ -191,4 +193,8 @@ nav: - "Troubleshooting": troubleshooting.md hooks: - - ./hooks/nightly_redirect.py \ No newline at end of file + - ./hooks/nightly_redirect.py + - ./hooks/nightly_banner.py + +exclude_docs: | + nightly-release.md diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 00000000..cb23fe08 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,10 @@ +{% extends "base.html" %} +{% block announce %} + + {%- if config.extra.nightly -%} + +
+ This is nightly documentation, and it may differ from stable. Please see here for stable documentation. +
+ {%- endif -%} +{% endblock %}