Skip to content

[WIP] Add versioning to the docs #869

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 36 commits into
base: main
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
1fd0314
contribution guide updates
artberger Mar 3, 2025
dbc3b22
image path relative
artberger Mar 3, 2025
7d8ecde
mike versioning
artberger Mar 3, 2025
ed87f3f
update doc guide
artberger Mar 3, 2025
c49b44d
period
artberger Mar 4, 2025
d313861
ensure version switcher remains visible
artberger Mar 4, 2025
196be29
fix formattin
artberger Mar 4, 2025
385f50d
fix location of main.html in overrides
artberger Mar 4, 2025
5769e8f
Add make virtual environment command
artberger Mar 4, 2025
f290f5f
add link to localhost
artberger May 8, 2025
a13e744
add warning
artberger May 8, 2025
7e68026
Add versioning to local docker image
artberger May 8, 2025
fa32888
Merge branch 'main' into adb-versioning
artberger May 8, 2025
2f26413
revert img update
artberger May 8, 2025
fa00351
make docs target and make-docs.sh script
artberger May 23, 2025
1405ff9
change from gh-pages to docs branch
artberger May 23, 2025
ff3d933
Update the release process to include make docs
artberger May 23, 2025
c88ecf6
Add versioning info to contributors guide
artberger May 23, 2025
fd463f1
update mike serve for docs branch
artberger May 23, 2025
dea46d3
Update docs guide
artberger May 23, 2025
b359ab2
Update Netlify settings and remove old make commands
artberger May 23, 2025
bba0257
update regex
artberger May 23, 2025
4a6789a
Update publish process
artberger May 23, 2025
0033ef3
fix branch name in description
artberger May 27, 2025
8e9f3d8
Set default version to latest
artberger May 27, 2025
992b3a7
Update deploy step
artberger May 27, 2025
29652fa
update release
artberger May 27, 2025
f20984f
update netlify.toml
artberger May 29, 2025
dccb488
change crd-ref-docs to be like Gateway API
artberger Jun 4, 2025
82cb314
rm crd-ref-docs from makefile
artberger Jun 4, 2025
5f26e56
rm api-ref-docs target and fix path
artberger Jun 4, 2025
facd790
fix latest tagging
artberger Jun 4, 2025
d16365c
fix latest
artberger Jun 4, 2025
deb8330
update mike server commands
artberger Jun 4, 2025
a892698
change from gh to git
artberger Jun 4, 2025
77612a0
add line
artberger Jun 4, 2025
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 2 additions & 3 deletions .github/ISSUE_TEMPLATE/new-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update release notes to mention that the docs are now automatically updated.


```shell
make release
Expand Down Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,6 @@ go.work.sum

# generated docs
site

# virtual environment for mkdocs
.venv
32 changes: 16 additions & 16 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added target to make a virtualenv, copied from the Gateway API project

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the virtualenv necessary if we have the build-docs target that uses a Docker container to build docs?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yeah, it wouldn't be needed for the local preview. I left it in for if people are doing local development on the docs theme. For example, if you needed to add some other mkdocs plugins down the road, or if you wanted to manually set the versions with mike (such as to remove an old version), it could be useful.

wdyt?

# docs since it installs mkdocs and all the right dependencies.
#
# On Ubuntu, this requires the python3-venv package.
virtualenv: .venv
Copy link
Contributor

@danehans danehans Jun 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checkout a release-0.4 branch, call this target and run make docs in the venv:

$ make docs
...
Deploying docs for version 0.4
unknown flag: --json

Usage:  gh release list [flags]

Flags:
      --exclude-drafts         Exclude draft releases
      --exclude-pre-releases   Exclude pre-releases
  -L, --limit int              Maximum number of items to fetch (default 30)

Error: Could not find any releases.
This version will be deployed, but not marked as 'latest'.
...
error: error writing commit:
  fatal: Can't create a branch from itself: docs
  fast-import: dumping crash report to .git/fast_import_crash_11185
make: *** [docs] Error 1

See #869 (comment) for an example that does not use gh.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the script not to use gh per your other comment.

Regarding the errors:

could not find any release

  • if this is from your fork, it might not have any releases to grab the latest version from, so it won't mark as latest, but it should still continue to generate it as a release

Can't create a branch from itself: docs

  • So how mike works is that it puts the versioned directories on a docs branch.
  • But if the branch does not exist, then it will get this error, which if it's your fork, I'm assuming it doesn't have that branch yet.
  • I put the steps as a prereq in the PR description, as we'd also have to make this branch in the GIE repo: [WIP] Add versioning to the docs #869 (comment)

.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

Expand Down Expand Up @@ -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.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added docs to the release target


##@ Dependencies

Expand Down
3 changes: 3 additions & 0 deletions hack/mkdocs/image/Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
5 changes: 4 additions & 1 deletion hack/mkdocs/image/entrypoint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does mike serve support --livereload by default?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, unfortunately I got this error and didn't see it in the --help or project :(

mike: error: unrecognized arguments: --live-reload

# Use mike serve for versioning support
mike serve -a 0.0.0.0:3000 --branch docs
1 change: 1 addition & 0 deletions hack/mkdocs/image/requirements.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
137 changes: 137 additions & 0 deletions hack/mkdocs/make-docs.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
#!/bin/bash
Copy link
Author

@artberger artberger May 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The make-docs.sh script

  • Reuses some of the front matter content from Gateway make docs
  • Gets version from the branch by using the git tool
  • Checks if the version should be marked as latest by using the gh tool
  • Builds API docs by calling the make target
  • Makes the versioned docs by using the mike tool

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The make docs script that the release calls would run this script. People could also check out the branch they want to build content for and run make docs.

Copy link
Contributor

@danehans danehans Jun 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@artberger I prefer not adding gh as a dependency. Instead of using gh, the following func finds the most‐recent semver‐style tag and compares it against MAJOR.MINOR.

# -----------------------------------------------------------------------------
# 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
    #    If branch’s MAJOR > latest_major, or (MAJOR == latest_major && MINOR ≥ latest_minor), it’s “latest” or newer.
    if (( MAJOR > latest_major )) || \
       (( MAJOR == latest_major && MINOR >= latest_minor )); then
        return 0
    fi

    return 1
}

Note: ^ needs to be tested to confirm expected results.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, the change from gh to git makes sense. I also updated it to fix an error that was tagging versions as latest that were equal or greater, so now it's just equal to latest. The update worked in the make docs and make live-docs previews for me.


# 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
12 changes: 9 additions & 3 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@artberger based on this CI error, Netlify is still expecting the site directory.

site_url: 'https://gateway-api-inference-extension.sigs.k8s.io/'
docs_dir: site-src
extra:
version:
provider: mike
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@artberger does mike also need to be added to the plugins list?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@danehans it can be if we want to change any of the default mike configuration values: https://github.com/jimporter/mike?tab=readme-ov-file#configuration

alias: true
extra_css:
- stylesheets/extra.css
theme:
Expand Down Expand Up @@ -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
Expand All @@ -77,3 +82,4 @@ nav:
- Contributing:
- How to Get Involved: contributing/index.md
- Developer Guide: contributing/devguide.md
- Documentation Guide: contributing/docs.md
16 changes: 12 additions & 4 deletions netlify.toml
Original file line number Diff line number Diff line change
@@ -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"
Loading