[WIP] Add versioning to the docs

.github/ISSUE_TEMPLATE/new-release.md

@@ -66,7 +66,7 @@ This document defines the process for releasing Gateway API Inference Extension.
      git checkout -b release-${MAJOR}.${MINOR} ${REMOTE}/release-${MAJOR}.${MINOR}
      ```
 
-4. Update release-specific content, generate release artifacts, and stage the changes.
+4. Update release-specific content, generate release artifacts, build the versioned docs, and stage the changes.
 
    ```shell
    make release
@@ -149,8 +149,7 @@ Use the following steps to announce the release.
 
 ## Final Steps
 
-1. Update docs in the `main` branch. <!-- link to example PR once we have one -->
-2. Close this issue.
+Close this issue.
 
 [repo]: https://github.com/kubernetes-sigs/gateway-api-inference-extension
 [staging registry]: https://console.cloud.google.com/artifacts/docker/k8s-staging-images/us-central1/gateway-api-inference-extension/epp

.gitignore

@@ -30,3 +30,6 @@ go.work.sum
 
 # generated docs
 site
+
+# virtual environment for mkdocs
+.venv

Makefile

@@ -260,28 +260,28 @@ bbr-image-kind: bbr-image-build ## Build the image and load it to kind cluster $
 
 ##@ Docs
 
-.PHONY: build-docs
-build-docs:
-	docker build --pull -t gaie/mkdocs hack/mkdocs/image
-	docker run --rm -v ${PWD}:/docs gaie/mkdocs build
 
-.PHONY: build-docs-netlify
-build-docs-netlify:
-	pip install -r hack/mkdocs/image/requirements.txt
-	python -m mkdocs build
+.PHONY: docs
+docs: ## Deploy documentation using mike, determining latest version from git tags.
+	chmod +x ./hack/mkdocs/make-docs.sh
+	./hack/mkdocs/make-docs.sh
 
 .PHONY: live-docs
 live-docs:
 	docker build -t gaie/mkdocs hack/mkdocs/image
 	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gaie/mkdocs
 
-.PHONY: api-ref-docs
-api-ref-docs:
-	crd-ref-docs \
-		--source-path=${PWD}/api \
-		--config=crd-ref-docs.yaml \
-		--renderer=markdown \
-		--output-path=${PWD}/site-src/reference/spec.md
+# Generate a virtualenv install, which is useful for hacking on the
+# docs since it installs mkdocs and all the right dependencies.
+#
+# On Ubuntu, this requires the python3-venv package.
+virtualenv: .venv
+.venv: hack/mkdocs/image/requirements.txt
+	@echo Creating a virtualenv in $@"... "
+	@python3 -m venv $@ || (rm -rf $@ && exit 1)
+	@echo Installing packages in $@"... "
+	@$@/bin/python3 -m pip install -q -r hack/mkdocs/image/requirements.txt || (rm -rf $@ && exit 1)
+	@echo To enter the virtualenv type \"source $@/bin/activate\",  to exit type \"deactivate\"
 
 ##@ Deployment
 
@@ -321,7 +321,7 @@ artifacts: kustomize
 	@$(call clean-manifests)
 
 .PHONY: release
-release: artifacts release-quickstart verify test # Create a release.
+release: artifacts release-quickstart verify test docs # Create a release.
 
 ##@ Dependencies
 

hack/mkdocs/image/Dockerfile

@@ -14,6 +14,9 @@
 
 FROM python:3.13-alpine
 
+# Install git, required for mike versioning
+RUN apk add --no-cache git
+
 COPY requirements.txt /requirements.txt
 RUN pip install -r /requirements.txt
 

hack/mkdocs/image/entrypoint.sh

@@ -22,7 +22,10 @@ CMD=$1
 if [ "$CMD" == "build" ];
 then
   mkdocs build
+  # Set the default version to latest after building
+  mike set-default --branch docs latest
   exit 0;
 fi
 
-mkdocs serve --dev-addr=0.0.0.0:3000 --livereload
+# Use mike serve for versioning support
+mike serve -a 0.0.0.0:3000 --branch docs

hack/mkdocs/image/requirements.txt

@@ -23,3 +23,4 @@ mkdocs-material==9.5.36
 mkdocs-material-extensions==1.3.1
 mkdocs-redirects==1.2.1
 mkdocs-mermaid2-plugin==1.1.1
+mike==2.1.3

hack/mkdocs/make-docs.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+
+# Copyright 2021 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+readonly SCRIPT_ROOT="$(cd "$(dirname "${BASH_SOURCE}")"/../.. && pwd)"
+cd $SCRIPT_ROOT
+
+# -----------------------------------------------------------------------------
+# Version extraction from git branch
+# -----------------------------------------------------------------------------
+get_version_from_branch() {
+    # Get current branch name
+    local branch_name
+    branch_name=$(git rev-parse --abbrev-ref HEAD)
+
+    # If the branch is main, set the version to main (and not a MAJOR.MINOR version)
+    if [[ "$branch_name" == "main" ]]; then
+        VERSION="main"
+
+    # Extract version from branch name (e.g., release-0.3 -> 0.3)
+    elif [[ $branch_name =~ release-([0-9]+)\.([0-9]+) ]]; then
+        MAJOR="${BASH_REMATCH[1]}"
+        MINOR="${BASH_REMATCH[2]}"
+        VERSION="${MAJOR}.${MINOR}"
+    else
+        echo "Error: Could not extract version from branch name: $branch_name"
+        echo "Expected branch name format: 'release-X.Y' or 'main'"
+        exit 1
+    fi
+}
+
+# -----------------------------------------------------------------------------
+# Check if version should be marked as latest (ignore release candidates "-rc" or any hyphenated suffix)
+# -----------------------------------------------------------------------------
+is_latest_version() {
+    # 1) List all tags matching semver-ish (vX.Y[.Z] or X.Y[.Z]), sort by version descending,
+    # and pick the very first one.
+    local latest_tag
+    latest_tag=$(git tag --list 'v[0-9]*.[0-9]*' --list '[0-9]*.[0-9]*' --sort=-v:refname | head -n1)
+
+    if [[ -z "$latest_tag" ]]; then
+        echo "Error: Could not find any semver‐style tags."
+        return 1
+    fi
+
+    # 2) Strip leading 'v', then drop anything after the first hyphen (e.g. "0.3.0-rc.1" → "0.3.0")
+    local bare="${latest_tag#v}"      # remove leading "v" if present
+    bare="${bare%%-*}"                # drop "-<anything>" (so "0.3.0-rc.1" → "0.3.0")
+
+    # 3) Now extract MAJOR and MINOR from e.g. "0.3.0" or "2.5"
+    if [[ "$bare" =~ ^([0-9]+)\.([0-9]+)(\.[0-9]+)?$ ]]; then
+        local latest_major="${BASH_REMATCH[1]}"
+        local latest_minor="${BASH_REMATCH[2]}"
+    else
+        echo "Error: Could not parse version from latest tag: ${latest_tag} (bare='${bare}')"
+        return 1
+    fi
+
+    # 4) Compare numeric MAJOR/MINOR for exact match
+    if (( MAJOR == latest_major && MINOR == latest_minor )); then
+        return 0
+    fi
+    return 1
+}
+
+# Get version from current branch
+get_version_from_branch
+
+# -----------------------------------------------------------------------------
+# Environment variables (defaults)
+# -----------------------------------------------------------------------------
+# VERSION is now set by get_version_from_branch()
+
+# Wrap sed to deal with GNU and BSD sed flags.
+run::sed() {
+    local -r vers="$(sed --version < /dev/null 2>&1 | grep -q GNU && echo gnu || echo bsd)"
+    case "$vers" in
+        gnu) sed -i "$@" ;;
+        *) sed -i '' "$@" ;;
+    esac
+}
+
+# -----------------------------------------------------------------------------
+# Build versioned docs
+# -----------------------------------------------------------------------------
+
+# Generate API docs
+
+GOPATH=${GOPATH:-$(go env GOPATH)}
+
+# "go env" doesn't print anything if GOBIN is the default, so we
+# have to manually default it.
+GOBIN=${GOBIN:-$(go env GOBIN)}
+GOBIN=${GOBIN:-${GOPATH}/bin}
+
+echo $GOBIN
+
+go install github.com/elastic/crd-ref-docs
+
+${GOBIN}/crd-ref-docs \
+    --source-path=${PWD}/api \
+    --config=crd-ref-docs.yaml \
+    --renderer=markdown \
+    --output-path=${PWD}/site-src/reference/spec.md
+
+# Deploy docs with mike
+echo "Deploying docs for version ${VERSION}"
+if [[ "$VERSION" == "main" ]]; then
+    echo "Deploying docs as 'main'."
+    mike deploy --push --branch docs main
+elif is_latest_version; then
+    echo "This version will be deployed and marked as 'latest'."
+    mike deploy --push --update-aliases --alias-type=copy --branch docs "${VERSION}" latest
+else
+    echo "This version will be deployed, but not marked as 'latest'."
+    mike deploy --push --branch docs "${VERSION}"
+fi
+
+# Always set the default version to 'latest'
+echo "Setting default version to 'latest'."
+mike set-default --branch docs latest

mkdocs.yml

@@ -2,7 +2,12 @@ site_name: Kubernetes Gateway API Inference Extension
 repo_url: https://github.com/kubernetes-sigs/gateway-api-inference-extension
 repo_name: kubernetes-sigs/gateway-api-inference-extension
 site_dir: site
+site_url: 'https://gateway-api-inference-extension.sigs.k8s.io/'
 docs_dir: site-src
+extra:
+  version:
+    provider: mike
+    alias: true
 extra_css:
   - stylesheets/extra.css
 theme:
@@ -51,9 +56,9 @@ nav:
   - Overview:
     - Introduction: index.md
     - Concepts:
-        API Overview: concepts/api-overview.md
-        Conformance: concepts/conformance.md
-        Roles and Personas: concepts/roles-and-personas.md
+      - API Overview: concepts/api-overview.md
+      - Conformance: concepts/conformance.md
+      - Roles and Personas: concepts/roles-and-personas.md
     - Implementations: 
       - Gateways: implementations/gateways.md
       - Model Servers: implementations/model-servers.md
@@ -77,3 +82,4 @@ nav:
   - Contributing:
     - How to Get Involved: contributing/index.md
     - Developer Guide: contributing/devguide.md
+    - Documentation Guide: contributing/docs.md

netlify.toml

@@ -1,6 +1,14 @@
 # netlify configuration
 [build]
-publish = "site"
-command = "make build-docs-netlify"
-# available here https://github.com/netlify/build-image/blob/focal/included_software.md#languages
-environment = { PYTHON_VERSION = "3.8" }
+  # Base directory is the root (/)
+  base = "/"
+  # Publish directory is the current directory (.)
+  publish = "."
+  # No build command needed since we're publishing from the docs branch
+  command = ""
+  # available here https://github.com/netlify/build-image/blob/focal/included_software.md#languages
+  environment = { PYTHON_VERSION = "3.8" }
+
+# Specify that we want to build from the docs branch
+[context.production]
+  branch = "docs"