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,7 +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 -->
+1. Update docs in the `main` branch. <!-- TODO: Update the step after figure out how Netlify gets triggered. link to example PR once we have one -->
 2. Close this issue.
 
 [repo]: https://github.com/kubernetes-sigs/gateway-api-inference-extension

.gitignore

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

Makefile

@@ -260,20 +260,22 @@ 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: crd-ref-docs
+crd-ref-docs: ## Install crd-ref-docs if not already installed
+	@which crd-ref-docs >/dev/null 2>&1 || { \
+		echo "Installing crd-ref-docs..."; \
+		GOBIN=$(LOCALBIN) go install github.com/elastic/crd-ref-docs@latest; \
+	}
+
+.PHONY: docs
+docs: crd-ref-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
+	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gaie/mkdocs mike serve -a 0.0.0.0:3000 --branch docs
 
 .PHONY: api-ref-docs
 api-ref-docs:
@@ -283,6 +285,18 @@ api-ref-docs:
 		--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
 
 ifndef ignore-not-found
@@ -321,7 +335,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

@@ -25,4 +25,5 @@ then
   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,114 @@
+#!/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
+# -----------------------------------------------------------------------------
+is_latest_version() {
+    # Get the latest release tag, checking more releases to find the true latest
+    local latest_tag
+    latest_tag=$(gh release list --limit 20 --json tagName --jq '.[0].tagName')
+
+    if [[ -z "$latest_tag" ]]; then
+        echo "Error: Could not find any releases."
+        return 1
+    fi
+
+    # Extract version from tag (handles both v0.2.0 and 0.2 formats)
+    if [[ $latest_tag =~ ^v?([0-9]+)\.([0-9]+)(\.[0-9]+)?$ ]]; then
+        local latest_major="${BASH_REMATCH[1]}"
+        local latest_minor="${BASH_REMATCH[2]}"
+
+        # Compare versions
+        if [[ "$MAJOR" -gt "$latest_major" ]] || \
+           ([[ "$MAJOR" -eq "$latest_major" ]] && [[ "$MINOR" -ge "$latest_minor" ]]); then
+            return 0  # Current version is newer or equal
+        fi
+    else
+        echo "Error: Could not parse version from latest tag: $latest_tag"
+        return 1
+    fi
+
+    return 1  # Current version is older
+}
+
+# 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
+make api-ref-docs
+
+# 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 --branch docs "${VERSION}" latest
+else
+    echo "This version will be deployed, but not marked as 'latest'."
+    mike deploy --push --branch docs "${VERSION}"
+fi

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,10 @@
 # netlify configuration
 [build]
-publish = "site"
-command = "make build-docs-netlify"
+publish = "."
+command = ""
 # available here https://github.com/netlify/build-image/blob/focal/included_software.md#languages
-environment = { PYTHON_VERSION = "3.8" }
+environment.PYTHON_VERSION = "3.8"
+
+# Specify that we want to build from the docs branch
+[context.production]
+  branch = "docs"