Added script to bookkeep doc versions

docs/scripts/bumpversion.sh

@@ -0,0 +1,129 @@
+#!/bin/bash
+
+source "${BASH_SOURCE%/*}/../../scripts/common.sh"
+
+# Configurable variables
+ROOT=$(realpath "$(dirname "${BASH_SOURCE[0]}")/../..")
+WEBSITE_HOME="https://openfactcheck.readthedocs.io/en"
+DOCS_HOME="docs"
+DOCS_LATEST="latest"
+DOCS_ROOT="$ROOT/$DOCS_HOME"
+DOCS_DEST="$ROOT/public"
+VERSION_FILE="$DOCS_ROOT/src/_static/versions.json"
+
+# Formats a version entry
+function format_version_entry {
+    local version=$1
+    echo "{\"name\": \"$version\", \"version\": \"v$version\", \"url\": \"$WEBSITE_HOME/$version/\"}"
+}
+
+# Formats the development version entry
+function format_dev_version_entry {
+    echo "{\"version\": \"dev\", \"url\": \"$WEBSITE_HOME/latest/\"}"
+}
+
+# Formats the stable version entry
+function format_stable_version_entry {
+    local version=$1
+    echo "{\"name\": \"$version (stable)\", \"version\": \"v$version\", \"url\": \"$WEBSITE_HOME/stable/\", \"preferred\": true}"
+}
+
+# Retrieves versions from versions.json
+function get_versions {
+    jq -r '.[] | .name' "$VERSION_FILE"
+}
+
+# Generate the version.json file
+function generate_versions_file {
+    local versions=$(get_versions)
+    local entries=($(format_dev_version_entry))
+    
+    for version in $versions; do
+        entries+=($(format_version_entry "$version"))
+    done
+
+    echo "${entries[@]}" | jq -s '.' > "$DOCS_DEST/version.json"
+}
+
+# Initialize default values
+dry_run=0
+new_version=""
+
+# Function to show help message
+function show_help {
+    echo "Usage: $0 [-d|--dryrun] -n|--new-version <version>"
+    echo "  -d, --dryrun: Dry run; do not write any changes, just print the output."
+    echo "  -n, --new-version: Specify the new version to be added. This is a required argument."
+}
+
+# Manual parsing of command-line options
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        (-d|--dryrun)
+            dry_run=1
+            shift
+            ;;
+        (-n|--new-version)
+            if [[ -n "$2" ]]; then
+                new_version="$2"
+                shift 2
+            else
+                echo "Error: Argument for $1 is missing."
+                show_help
+                exit 1
+            fi
+            ;;
+        (-h|--help)
+            show_help
+            exit 0
+            ;;
+        (*)
+            echo "Invalid option: $1"
+            show_help
+            exit 1
+            ;;
+    esac
+done
+
+# Check if new version was specified
+if [[ -z "$new_version" ]]; then
+    echo "Error: -n|--new-version is required."
+    show_help
+    exit 1
+fi
+
+# Check if new version was specified
+if [[ -z "$new_version" ]]; then
+    echo "Error: -n new_version is required."
+    show_help
+    exit 1
+fi
+
+# Check the last stable version
+current_versions=$(get_versions)
+stable_version=$(echo "$current_versions" | tail -n +2 | head -n 1 | cut -d' ' -f1)
+echo "Last Stable version: $stable_version"
+
+# Check the old versions
+old_versions=($(echo "$current_versions" | tail -n +3))
+old_versions+=("$stable_version")
+old_versions=($(printf '%s\n' "${old_versions[@]}" | tac))
+echo "Old versions: ${old_versions[*]}"
+
+# Create new version entry
+if echo "${old_versions[@]}" | grep -q "$new_version"; then
+    echo "Version $new_version already exists in versions.json"
+    exit 1
+fi
+
+entries=( $(format_dev_version_entry) $(format_stable_version_entry "$new_version") )
+for version in ${old_versions[@]}; do
+    entries+=( $(format_version_entry "$version") )
+done
+
+if [ "$dry_run" -eq 1 ]; then
+    echo "$(echo ${entries[@]} | jq -s '.')"
+else
+    echo "Writing to versions.json"
+    echo "$(echo ${entries[@]} | jq -s '.')" > "$VERSION_FILE"
+fi

docs/src/_static/versions.json

@@ -1,12 +1,12 @@
 [
-    {
-        "version": "dev",
-        "url": "https://openfactcheck.readthedocs.io/en/latest/"
-    },
-    {
-        "name": "0.2.2 (stable)",
-        "version": "v0.2.2",
-        "url": "https://openfactcheck.readthedocs.io/en/stable/",
-        "preferred": true
-    }
+  {
+    "version": "dev",
+    "url": "https://openfactcheck.readthedocs.io/en/latest/"
+  },
+  {
+    "name": "0.2.2 (stable)",
+    "version": "v0.2.2",
+    "url": "https://openfactcheck.readthedocs.io/en/stable/",
+    "preferred": true
+  }
 ]

docs/src/conf.py

@@ -127,6 +127,7 @@ json_url = "https://openfactcheck.readthedocs.io/en/latest/_static/versions.json
 # Define the version we use for matching in the version switcher.
 version_match = os.environ.get("READTHEDOCS_VERSION")
 release = openfactcheck.__version__
+
 # If READTHEDOCS_VERSION doesn't exist, we're not on RTD
 # If it is an integer, we're in a PR build and the version isn't correct.
 # If it's "latest" → change to "dev" (that's what we want the switcher to call it)
@@ -136,7 +137,7 @@ if not version_match or version_match.isdigit() or version_match == "latest":
         version_match = "dev"
         # We want to keep the relative reference if we are in dev mode
         # but we want the whole url if we are effectively in a released version
-        json_url = "_static/switcher.json"
+        json_url = "_static/versions.json"
     else:
         version_match = f"v{release}"
 elif version_match == "stable":
@@ -174,7 +175,7 @@ html_theme_options = {
     "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
     # "show_nav_level": 2,
     # "announcement": "https://raw.githubusercontent.com/pydata/pydata-sphinx-theme/main/docs/_templates/custom-template.html",
-    # "show_version_warning_banner": True,
+    "show_version_warning_banner": True,
     # "navbar_center": ["navbar-nav"],
     # "navbar_start": ["navbar-logo"],
     "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],

docs/versions.py

@@ -1,42 +0,0 @@
-"""Module for generating switch.json file."""
-
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import json
-import os
-
-ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
-WEBSITE_HOME = "https://openfactcheck.readthedocs.io/en/"
-DOCS_HOME = "docs"
-DOCS_LATEST = "latest"
-DOCS_ROOT = os.path.join(ROOT, DOCS_HOME)
-DOCS_DEST = os.path.join(ROOT, "public")
-VERSION_FILE = os.path.join(DOCS_ROOT, "src", "_static", "versions.json")
-
-
-def format_version_entry(version: str) -> dict[str, str]:
-    """Format a single entry of switcher.json, as expected by `pydata-sphinx-theme`."""
-    return {
-        "url": "/".join((WEBSITE_HOME, version, "")),
-        "version": version,
-    }
-
-
-def validate_docs_folder(path: str) -> bool:
-    """Check that folder with path specified contains valid documentation."""
-    return os.path.isdir(path) and os.path.isfile(os.path.join(path, "index.html"))
-
-
-def get_versions() -> list[str]:
-    """List available versions of the package in the expected order."""
-    with open(VERSION_FILE) as infile:
-        versions = json.load(infile)
-
-    print("Available versions:")
-    for version in versions:
-        print(f"  - {version}")
-
-
-if __name__ == "__main__":
-    get_versions()

scripts/release.sh

@@ -104,6 +104,7 @@ echo
 # Modify the VERSION file
 printf "$VERSION" > ./VERSION
 bump2version patch --new-version $VERSION_BUMP --allow-dirty --verbose 
+./docs/scripts/bumpversion.sh --new-version $VERSION_BUMP
 
 # Commit and tag the release
 git add ./VERSION
@@ -111,6 +112,7 @@ git add ./.bumpversion.cfg
 git add ./pyproject.toml
 git add ./pre-requirements.txt
 git add ./src/openfactcheck/__init__.py
+git add ./docs/src/_static/versions.json
 git commit -m "🚀 $MESSAGE"
 git tag $VERSION
 git push origin $BRANCH