-
Notifications
You must be signed in to change notification settings - Fork 115
[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
base: main
Are you sure you want to change the base?
Changes from all commits
1fd0314
dbc3b22
7d8ecde
ed87f3f
c49b44d
d313861
196be29
385f50d
5769e8f
f290f5f
a13e744
7e68026
fa32888
2f26413
fa00351
1405ff9
ff3d933
c88ecf6
fd463f1
dea46d3
b359ab2
bba0257
4a6789a
0033ef3
8e9f3d8
992b3a7
29652fa
f20984f
dccb488
82cb314
5f26e56
facd790
d16365c
deb8330
a892698
77612a0
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -30,3 +30,6 @@ go.work.sum | |
|
||
# generated docs | ||
site | ||
|
||
# virtual environment for mkdocs | ||
.venv |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added target to make a virtualenv, copied from the Gateway API project There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Is the There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 wdyt? |
||
# docs since it installs mkdocs and all the right dependencies. | ||
# | ||
# On Ubuntu, this requires the python3-venv package. | ||
virtualenv: .venv | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I checkout a $ 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 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I updated the script not to use Regarding the errors:
|
||
.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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Added docs to the release target |
||
|
||
##@ Dependencies | ||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Does There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
|
||
# Use mike serve for versioning support | ||
mike serve -a 0.0.0.0:3000 --branch docs |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,137 @@ | ||
#!/bin/bash | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The make-docs.sh script
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @artberger I prefer not adding # -----------------------------------------------------------------------------
# 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks, the change from |
||
|
||
# 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 |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @artberger based on this CI error, Netlify is still expecting the |
||
site_url: 'https://gateway-api-inference-extension.sigs.k8s.io/' | ||
docs_dir: site-src | ||
extra: | ||
version: | ||
provider: mike | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @artberger does There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 |
||
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 |
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" |
There was a problem hiding this comment.
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.