From 1fd03146afecaca995035d45ef8fe6f5d11a3cdf Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 3 Mar 2025 14:58:14 -0500 Subject: [PATCH 01/35] contribution guide updates --- site-src/contributing/docs.md | 119 ++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 site-src/contributing/docs.md diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md new file mode 100644 index 000000000..86f6e0abd --- /dev/null +++ b/site-src/contributing/docs.md @@ -0,0 +1,119 @@ +# Contributing to the docs + +This doc site is built using MkDocs. It includes a Docker image for you to preview local changes without needing to set up MkDocs and its related plug-ins. + +## Preview local changes + +1. In the `site-src` directory, make your changes to the Markdown files. + +2. If you add a new page, make sure to update the `nav` section in the `mkdocs.yml` file. + +3. From the root directory of this project, run the Docker image with the following command from the `Makefile` + ```sh + make live-docs + ``` + +## Style guides + +Refer to the following style guides: + +* [Gateway API](https://gateway-api.sigs.k8s.io/contributing/style-guide/) +* [Kubernetes](https://kubernetes.io/docs/contribute/style/style-guide/) + +If you need guidance on specific words that are not covered in one of those style guides, check a common cloud provider, such as [Google developer docs](https://developers.google.com/style). + +## Version the docs + +The Material theme uses `mike` to version the docs. The following steps cover common workflows for versioning. For more information, see the following resources: + +* [Material theme versioning page](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/) +* [mike readme](https://github.com/jimporter/mike) + +Example workflow for using `mike`: + +1. List the current versions. Aliases are included in brackets. + ```sh + mike list + + # Example output + 0.3 [main] + 0.2 [latest] + 0.1 + ``` + +2. In the `site-src` directory, make and save your doc changes. + +3. Add the changes to the versions that you want to publish them in. The following example adds the changes to both the latest 0.2 and 0.3 main versions. + ```sh + mike deploy --push --update-aliases 0.3 main + mike deploy --push --update-aliases 0.2 latest + ``` + +4. Optional: Add a new version of the docs. The following example adds a new version 0.4 as main based on the current content, renames 0.3 to latest with the current content, removes the latest alias from 0.2 but leaves the version content untouched, and deletes version 0.1. + ```sh + mike delete latest + mike deploy --push --update-aliases 0.4 main + mike deploy --push --update-aliases 0.3 latest + mike delete 0.1 + ``` + +The `mike` commands add each version as a separate commit and directory on the `gh-pages` branch. + +The doc builds then publish the versioned content from this branch to the website. + +## Add MkDocs features like plug-ins + +As you contribute to the Kubernetes Gateway API Inference Extension project, you might want to add features to the MkDocs theme or build process. The following sections explain how to set up a local docs development environment and contribute to the docs build processes. + +### Set up your local docs dev environment + +To install and use `mkdocs`, refer to the [MkDocs User Guide](https://www.mkdocs.org/user-guide/). + +1. Make sure that you have a recent version of `python` and `pip`. + +2. You also might want to set up a Python virtual environment for the `gateway-api-inference-extension` project. + ```sh + python -m venv ~/.venvs/gateway-api-inference-extension + source ~/.venvs/gateway-api-inference-extension/bin/activate + ``` + +3. Install MkDocs with the theme and plugins that this project uses. + ```sh + # Install mkdocs + pip install mkdocs + + # Install the Material theme that this project uses + pip install mkdocs-material + + # Install the plugins that this project uses + # For a full list, check the /hack/mkdocs/image/requirements.txt + pip install mkdocs-awesome-pages-plugin + pip install mkdocs-macros-plugin + pip install mkdocs-mermaid2-plugin + pip install mkdocs-material-extensions + pip install mkdocs-redirects + pip install mike + ``` + +### Add MkDocs plugins + +1. Try out the MkDocs plugin that you want to add locally. For more info, see the [MkDocs Plugin docs](https://squidfunk.github.io/mkdocs-material/plugins/). + +2. Add the plugin to the `/hack/mkdocs/image/requirements.txt` file. + +3. From the root directory, run the Docker image of the docs. Make sure that the plugin builds and works as you expect. + ```sh + make live-docs + ``` + +## Publish the docs + +The project uses Netlify to host the docs. + +You can locally build the files that become the doc site. For example, you might want to check the HTML output of changes that you make to the site. + +```sh +make build-docs-netlify +``` + +The Gateway API Inference Extension team will publish the docs based on the latest changes in the `main` branch. \ No newline at end of file From dbc3b22830aa69f1854b63223f58ca2f161bd5a6 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 3 Mar 2025 14:58:38 -0500 Subject: [PATCH 02/35] image path relative the previous /images/ does not work when the content is versioned --- site-src/api-types/inferencepool.md | 2 +- site-src/concepts/api-overview.md | 2 +- site-src/index.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/site-src/api-types/inferencepool.md b/site-src/api-types/inferencepool.md index baa604b61..4e6b67d4d 100644 --- a/site-src/api-types/inferencepool.md +++ b/site-src/api-types/inferencepool.md @@ -25,7 +25,7 @@ Additionally, any Pod that seeks to join an InferencePool would need to support `InferencePool` has some small overlap with `Service`, displayed here: -Comparing InferencePool with Service +Comparing InferencePool with Service The InferencePool is _not_ intended to be a mask of the Service object, simply exposing the absolute bare minimum required to allow the Platform Admin to focus less on networking, and more on Pool management. diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index 9c5c04163..c080ee6ad 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -3,7 +3,7 @@ ## Background The Gateway API Inference Extension project is an extension of the Kubernetes Gateway API for serving Generative AI models on Kubernetes. Gateway API Inference Extension facilitates standardization of APIs for Kubernetes cluster operators and developers running generative AI inference, while allowing flexibility for underlying gateway implementations (such as Envoy Proxy) to iterate on mechanisms for optimized serving of models. -Overview of API integration +Overview of API integration ## API Resources diff --git a/site-src/index.md b/site-src/index.md index 04d1fadb8..d781ca1dc 100644 --- a/site-src/index.md +++ b/site-src/index.md @@ -9,7 +9,7 @@ The overall resource model focuses on 2 new inference-focused they are expected to manage: -Gateway API Inference Extension Resource Model +Gateway API Inference Extension Resource Model ## Key Features Gateway API Inference Extension, along with a reference implementation in Envoy Proxy, provides the following key features: @@ -82,7 +82,7 @@ routed to. 5. The Gateway will route the request to the desired endpoint. -Gateway API Inference Extension Request Flow +Gateway API Inference Extension Request Flow ## Who is working on Gateway API Inference Extension? From 7d8ecde27f646ad8f79632fa56f6ab4c832cd0eb Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 3 Mar 2025 14:58:48 -0500 Subject: [PATCH 03/35] mike versioning --- hack/mkdocs/image/requirements.txt | 1 + mkdocs.yml | 12 +++++++++--- site-src/overrides/partials/main.html | 8 ++++++++ 3 files changed, 18 insertions(+), 3 deletions(-) create mode 100644 site-src/overrides/partials/main.html diff --git a/hack/mkdocs/image/requirements.txt b/hack/mkdocs/image/requirements.txt index e7cb9b0c6..7f5144c0f 100644 --- a/hack/mkdocs/image/requirements.txt +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 8cd3f3fba..8ae77882c 100644 --- a/mkdocs.yml +++ b/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: @@ -48,9 +53,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: implementations.md - FAQ: faq.md - Guides: @@ -69,3 +74,4 @@ nav: - Contributing: - How to Get Involved: contributing/index.md - Developer Guide: contributing/devguide.md + - Documentation Guide: contributing/docs.md diff --git a/site-src/overrides/partials/main.html b/site-src/overrides/partials/main.html new file mode 100644 index 000000000..3cf182cfa --- /dev/null +++ b/site-src/overrides/partials/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} + You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %} \ No newline at end of file From ed87f3fab8a39b234a7e114aaacfcc2cdd266002 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Mon, 3 Mar 2025 15:17:26 -0500 Subject: [PATCH 04/35] update doc guide --- site-src/contributing/docs.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index 86f6e0abd..20f5804a2 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -27,7 +27,7 @@ If you need guidance on specific words that are not covered in one of those styl The Material theme uses `mike` to version the docs. The following steps cover common workflows for versioning. For more information, see the following resources: * [Material theme versioning page](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/) -* [mike readme](https://github.com/jimporter/mike) +* [`mike` readme](https://github.com/jimporter/mike) Example workflow for using `mike`: @@ -57,7 +57,23 @@ Example workflow for using `mike`: mike delete 0.1 ``` -The `mike` commands add each version as a separate commit and directory on the `gh-pages` branch. +The `mike` commands add each version as a separate commit and directory on the `gh-pages` branch. +* The versioned directories contain the output of the MkDocs build for each version. +* The `latest` and `main` aliases are copies of the versioned directories. +* The `versions.json` file has the information for each version and alias that `mike` tracks. You can check this if you use + +Example directory structure: + +```plaintext +gh-pages branch +│── 0.1/ +│── 0.2/ +│── 0.3/ +│── 0.4/ +│── latest/ +│── main/ +│── versions.json +``` The doc builds then publish the versioned content from this branch to the website. From c49b44d921fa5f68bc145885ec6ef97950196031 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 4 Mar 2025 11:38:44 -0500 Subject: [PATCH 05/35] period --- site-src/contributing/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index 20f5804a2..ed816d4ed 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -8,7 +8,7 @@ This doc site is built using MkDocs. It includes a Docker image for you to previ 2. If you add a new page, make sure to update the `nav` section in the `mkdocs.yml` file. -3. From the root directory of this project, run the Docker image with the following command from the `Makefile` +3. From the root directory of this project, run the Docker image with the following command from the `Makefile`. ```sh make live-docs ``` From d313861ac6b4808dafb5af9c82cc8e2268222181 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 4 Mar 2025 12:06:25 -0500 Subject: [PATCH 06/35] ensure version switcher remains visible otherwise, it did not appear because its in the same header_topic element that was getting hidden --- site-src/stylesheets/extra.css | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/site-src/stylesheets/extra.css b/site-src/stylesheets/extra.css index e42cfb893..ee9e61c2d 100644 --- a/site-src/stylesheets/extra.css +++ b/site-src/stylesheets/extra.css @@ -1,8 +1,13 @@ /* Hide title in favor of logo */ -.md-header__topic { +.md-header__topic .md-ellipsis { display: none; } +/* Ensure the version switcher remains visible */ +.md-header__topic .md-version { + display: block; +} + /* Use Kubernetes color as primary */ :root { --md-primary-fg-color: #326ce5; From 196be29857d039b335349ba9e420eaee24a0c9d7 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 4 Mar 2025 12:54:49 -0500 Subject: [PATCH 07/35] fix formattin --- site-src/contributing/docs.md | 1 + 1 file changed, 1 insertion(+) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index ed816d4ed..4deb1352a 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -58,6 +58,7 @@ Example workflow for using `mike`: ``` The `mike` commands add each version as a separate commit and directory on the `gh-pages` branch. + * The versioned directories contain the output of the MkDocs build for each version. * The `latest` and `main` aliases are copies of the versioned directories. * The `versions.json` file has the information for each version and alias that `mike` tracks. You can check this if you use From 385f50de0b117b15b682f2bef342f9d7edd62131 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 4 Mar 2025 14:42:30 -0500 Subject: [PATCH 08/35] fix location of main.html in overrides --- site-src/overrides/{partials => }/main.html | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename site-src/overrides/{partials => }/main.html (100%) diff --git a/site-src/overrides/partials/main.html b/site-src/overrides/main.html similarity index 100% rename from site-src/overrides/partials/main.html rename to site-src/overrides/main.html From 5769e8f3a0eef7f65948adc5a94cb2cb1de00107 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 4 Mar 2025 17:02:57 -0500 Subject: [PATCH 09/35] Add make virtual environment command Based on Gateway API https://github.com/kubernetes-sigs/gateway-api/blob/main/Makefile#L162-L172 --- .gitignore | 3 +++ Makefile | 12 ++++++++++ site-src/contributing/docs.md | 45 ++++++++++------------------------- 3 files changed, 28 insertions(+), 32 deletions(-) diff --git a/.gitignore b/.gitignore index 4442b6516..237f2fbd4 100644 --- a/.gitignore +++ b/.gitignore @@ -30,3 +30,6 @@ go.work.sum # generated docs site + +# virtual environment for mkdocs +.venv \ No newline at end of file diff --git a/Makefile b/Makefile index 8d02a5e8c..6a446898d 100644 --- a/Makefile +++ b/Makefile @@ -228,6 +228,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 diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index 4deb1352a..bd9e7d906 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -78,47 +78,28 @@ gh-pages branch The doc builds then publish the versioned content from this branch to the website. -## Add MkDocs features like plug-ins +## Develop the MkDocs theme -As you contribute to the Kubernetes Gateway API Inference Extension project, you might want to add features to the MkDocs theme or build process. The following sections explain how to set up a local docs development environment and contribute to the docs build processes. +As you contribute to the Kubernetes Gateway API Inference Extension project, you might want to add features to the MkDocs theme or build process. -### Set up your local docs dev environment - -To install and use `mkdocs`, refer to the [MkDocs User Guide](https://www.mkdocs.org/user-guide/). - -1. Make sure that you have a recent version of `python` and `pip`. +Helpful resources: + +* [Customization, extensions, and overrides](https://squidfunk.github.io/mkdocs-material/customization/) +* [Setup features](https://squidfunk.github.io/mkdocs-material/setup/) +* [Plugins](https://squidfunk.github.io/mkdocs-material/plugins/) -2. You also might want to set up a Python virtual environment for the `gateway-api-inference-extension` project. - ```sh - python -m venv ~/.venvs/gateway-api-inference-extension - source ~/.venvs/gateway-api-inference-extension/bin/activate - ``` +General steps: -3. Install MkDocs with the theme and plugins that this project uses. +1. Set up a virtual environment with python, pip, mkdocs, and the plugins that this project uses. ```sh - # Install mkdocs - pip install mkdocs - - # Install the Material theme that this project uses - pip install mkdocs-material - - # Install the plugins that this project uses - # For a full list, check the /hack/mkdocs/image/requirements.txt - pip install mkdocs-awesome-pages-plugin - pip install mkdocs-macros-plugin - pip install mkdocs-mermaid2-plugin - pip install mkdocs-material-extensions - pip install mkdocs-redirects - pip install mike + make virtualenv ``` -### Add MkDocs plugins - -1. Try out the MkDocs plugin that you want to add locally. For more info, see the [MkDocs Plugin docs](https://squidfunk.github.io/mkdocs-material/plugins/). +2. Try out the MkDocs Material theme features, plugins, or other customizations that you want to add locally. -2. Add the plugin to the `/hack/mkdocs/image/requirements.txt` file. +3. For plugins, add the plugin to the `/hack/mkdocs/image/requirements.txt` file. -3. From the root directory, run the Docker image of the docs. Make sure that the plugin builds and works as you expect. +4. From the root directory, run the Docker image of the docs. Make sure that your changes build and works as you expect. ```sh make live-docs ``` From f290f5f238e22fa2fa8d16b241fed8167ac943c1 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Thu, 8 May 2025 09:56:06 -0400 Subject: [PATCH 10/35] add link to localhost --- site-src/contributing/docs.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index bd9e7d906..c1c12fefa 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -13,6 +13,8 @@ This doc site is built using MkDocs. It includes a Docker image for you to previ make live-docs ``` +4. Open your browser to preview the local build, typically at [http://localhost:3000](http://localhost:3000). + ## Style guides Refer to the following style guides: From a13e744a721c629e398eb906c376292bb5647b07 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Thu, 8 May 2025 11:44:54 -0400 Subject: [PATCH 11/35] add warning --- site-src/contributing/docs.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index c1c12fefa..f65121915 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -13,7 +13,10 @@ This doc site is built using MkDocs. It includes a Docker image for you to previ make live-docs ``` -4. Open your browser to preview the local build, typically at [http://localhost:3000](http://localhost:3000). +4. Open your browser to preview the local build, [http://localhost:3000](http://localhost:3000). + +!!! type "One preview at a time" + For better performance, open one localhost preview at a time. If you have multiple browsers rendering `localhost:3000`, you might notice a lag time in loading pages. ## Style guides From 7e68026685f160daf3aae2044f60561f50de2cf2 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Thu, 8 May 2025 11:45:52 -0400 Subject: [PATCH 12/35] Add versioning to local docker image --- Makefile | 2 +- hack/mkdocs/image/Dockerfile | 3 +++ hack/mkdocs/image/entrypoint.sh | 3 ++- 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index 6a446898d..fe19ac332 100644 --- a/Makefile +++ b/Makefile @@ -218,7 +218,7 @@ build-docs-netlify: .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 .PHONY: api-ref-docs api-ref-docs: diff --git a/hack/mkdocs/image/Dockerfile b/hack/mkdocs/image/Dockerfile index 87e5bd7bf..4cc9f9e10 100644 --- a/hack/mkdocs/image/Dockerfile +++ b/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 diff --git a/hack/mkdocs/image/entrypoint.sh b/hack/mkdocs/image/entrypoint.sh index 9e7accc0c..45b78cd24 100755 --- a/hack/mkdocs/image/entrypoint.sh +++ b/hack/mkdocs/image/entrypoint.sh @@ -25,4 +25,5 @@ then exit 0; fi -mkdocs serve --dev-addr=0.0.0.0:3000 --livereload \ No newline at end of file +# Use mike serve for versioning support +mike serve -a 0.0.0.0:3000 \ No newline at end of file From 2f264134893ca7092280a9fb03698827ee6e5d35 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Thu, 8 May 2025 14:46:02 -0400 Subject: [PATCH 13/35] revert img update --- site-src/api-types/inferencepool.md | 2 +- site-src/concepts/api-overview.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/site-src/api-types/inferencepool.md b/site-src/api-types/inferencepool.md index 73a762350..1494d314e 100644 --- a/site-src/api-types/inferencepool.md +++ b/site-src/api-types/inferencepool.md @@ -54,7 +54,7 @@ In this example: **InferencePool** has some small overlap with **Service**, displayed here: -Comparing InferencePool with Service +Comparing InferencePool with Service The InferencePool is not intended to be a mask of the Service object. It provides a specialized abstraction tailored for managing and routing traffic to groups of LLM model servers, allowing Platform Admins to focus on pool-level management rather than low-level networking details. diff --git a/site-src/concepts/api-overview.md b/site-src/concepts/api-overview.md index 9087a7f15..921b6fa45 100644 --- a/site-src/concepts/api-overview.md +++ b/site-src/concepts/api-overview.md @@ -3,7 +3,7 @@ ## Background The Gateway API Inference Extension project is an extension of the Kubernetes Gateway API for serving Generative AI models on Kubernetes. Gateway API Inference Extension facilitates standardization of APIs for Kubernetes cluster operators and developers running generative AI inference, while allowing flexibility for underlying gateway implementations (such as Envoy Proxy) to iterate on mechanisms for optimized serving of models. -Overview of API integration +Overview of API integration ## API Resources From fa00351f30ec457680616441a09b6501ab587b41 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 09:11:03 -0400 Subject: [PATCH 14/35] make docs target and make-docs.sh script --- Makefile | 13 +++++ hack/mkdocs/make-docs.sh | 114 +++++++++++++++++++++++++++++++++++++ site-src/reference/spec.md | 34 ++++++++--- 3 files changed, 153 insertions(+), 8 deletions(-) create mode 100755 hack/mkdocs/make-docs.sh diff --git a/Makefile b/Makefile index 1c2b18449..bc100b5a0 100644 --- a/Makefile +++ b/Makefile @@ -270,6 +270,18 @@ 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 @@ -334,6 +346,7 @@ artifacts: kustomize .PHONY: release release: artifacts release-quickstart verify test # Create a release. +# TODO: add a docs target in between release-quickstart and verify ##@ Dependencies diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh new file mode 100755 index 000000000..2be6feef0 --- /dev/null +++ b/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 (e.g., v0.3.0 -> 0.3) + if [[ $latest_tag =~ v([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 main +elif is_latest_version; then + echo "This version will be deployed and marked as 'latest'." + mike deploy --push --update-aliases "${VERSION}" latest +else + echo "This version will be deployed, but not marked as 'latest'." + mike deploy --push "${VERSION}" +fi diff --git a/site-src/reference/spec.md b/site-src/reference/spec.md index d8e0c95bf..c76caa6a1 100644 --- a/site-src/reference/spec.md +++ b/site-src/reference/spec.md @@ -21,7 +21,7 @@ inference.networking.x-k8s.io API group. _Underlying type:_ _string_ Criticality defines how important it is to serve the model compared to other models. -Criticality is intentionally a bounded enum to contain the possibilities that need to be supported by the load balancing algorithm. Any reference to the Criticality field must be optional(use a pointer), and set no default. +Criticality is intentionally a bounded enum to contain the possibilities that need to be supported by the load balancing algorithm. Any reference to the Criticality field must be optional (use a pointer), and set no default. This allows us to union this with a oneOf field in the future should we wish to adjust/extend this behavior. _Validation:_ @@ -69,7 +69,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `group` _[Group](#group)_ | Group is the group of the referent.
The default value is "", representing the Core API group. | | MaxLength: 253
Pattern: `^$\|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
| -| `kind` _[Kind](#kind)_ | Kind is the Kubernetes resource kind of the referent. For example
"Service".
Defaults to "Service" when not specified.
ExternalName services can refer to CNAME DNS records that may live
outside of the cluster and as such are difficult to reason about in
terms of conformance. They also may not be safe to forward to (see
CVE-2021-25740 for more information). Implementations MUST NOT
support ExternalName Services. | Service | MaxLength: 63
MinLength: 1
Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
| +| `kind` _[Kind](#kind)_ | Kind is the Kubernetes resource kind of the referent. For example
"Service".

Defaults to "Service" when not specified.

ExternalName services can refer to CNAME DNS records that may live
outside of the cluster and as such are difficult to reason about in
terms of conformance. They also may not be safe to forward to (see
CVE-2021-25740 for more information). Implementations MUST NOT
support ExternalName Services. | Service | MaxLength: 63
MinLength: 1
Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
| | `name` _[ObjectName](#objectname)_ | Name is the name of the referent. | | MaxLength: 253
MinLength: 1
Required: \{\}
| | `portNumber` _[PortNumber](#portnumber)_ | The port number on the service running the extension. When unspecified,
implementations SHOULD infer a default value of 9002 when the Kind is
Service. | | Maximum: 65535
Minimum: 1
| | `failureMode` _[ExtensionFailureMode](#extensionfailuremode)_ | Configures how the gateway handles the case when the extension is not responsive.
Defaults to failClose. | FailClose | Enum: [FailOpen FailClose]
| @@ -125,7 +125,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `group` _[Group](#group)_ | Group is the group of the referent.
The default value is "", representing the Core API group. | | MaxLength: 253
Pattern: `^$\|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
| -| `kind` _[Kind](#kind)_ | Kind is the Kubernetes resource kind of the referent. For example
"Service".
Defaults to "Service" when not specified.
ExternalName services can refer to CNAME DNS records that may live
outside of the cluster and as such are difficult to reason about in
terms of conformance. They also may not be safe to forward to (see
CVE-2021-25740 for more information). Implementations MUST NOT
support ExternalName Services. | Service | MaxLength: 63
MinLength: 1
Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
| +| `kind` _[Kind](#kind)_ | Kind is the Kubernetes resource kind of the referent. For example
"Service".

Defaults to "Service" when not specified.

ExternalName services can refer to CNAME DNS records that may live
outside of the cluster and as such are difficult to reason about in
terms of conformance. They also may not be safe to forward to (see
CVE-2021-25740 for more information). Implementations MUST NOT
support ExternalName Services. | Service | MaxLength: 63
MinLength: 1
Pattern: `^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$`
| | `name` _[ObjectName](#objectname)_ | Name is the name of the referent. | | MaxLength: 253
MinLength: 1
Required: \{\}
| | `portNumber` _[PortNumber](#portnumber)_ | The port number on the service running the extension. When unspecified,
implementations SHOULD infer a default value of 9002 when the Kind is
Service. | | Maximum: 65535
Minimum: 1
| @@ -137,17 +137,22 @@ _Underlying type:_ _string_ Group refers to a Kubernetes Group. It must either be an empty string or a RFC 1123 subdomain. + This validation is based off of the corresponding Kubernetes validation: https://github.com/kubernetes/apimachinery/blob/02cfb53916346d085a6c6c7c66f882e3c6b0eca6/pkg/util/validation/validation.go#L208 + Valid values include: + * "" - empty string implies core Kubernetes API group * "gateway.networking.k8s.io" * "foo.example.com" + Invalid values include: + * "example.com/bar" - "/" is an invalid character _Validation:_ @@ -191,6 +196,7 @@ InferenceModel is the Schema for the InferenceModels API. InferenceModelSpec represents the desired state of a specific model use case. This resource is managed by the "Inference Workload Owner" persona. + The Inference Workload Owner persona is someone that trains, verifies, and leverages a large language model from a model frontend, drives the lifecycle and rollout of new versions of those models, and defines the specific @@ -198,6 +204,7 @@ performance and latency goals for the model. These workloads are expected to operate within an InferencePool sharing compute capacity with other InferenceModels, defined by the Inference Platform Admin. + InferenceModel's modelName (not the ObjectMeta name) is unique for a given InferencePool, if the name is reused, an error will be shown on the status of a InferenceModel that attempted to reuse. The oldest InferenceModel, based on @@ -212,7 +219,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `modelName` _string_ | ModelName is the name of the model as it will be set in the "model" parameter for an incoming request.
ModelNames must be unique for a referencing InferencePool
(names can be reused for a different pool in the same cluster).
The modelName with the oldest creation timestamp is retained, and the incoming
InferenceModel is sets the Ready status to false with a corresponding reason.
In the rare case of a race condition, one Model will be selected randomly to be considered valid, and the other rejected.
Names can be reserved without an underlying model configured in the pool.
This can be done by specifying a target model and setting the weight to zero,
an error will be returned specifying that no valid target model is found. | | MaxLength: 256
Required: \{\}
| -| `criticality` _[Criticality](#criticality)_ | Criticality defines how important it is to serve the model compared to other models referencing the same pool.
Criticality impacts how traffic is handled in resource constrained situations. It handles this by
queuing or rejecting requests of lower criticality. InferenceModels of an equivalent Criticality will
fairly share resources over throughput of tokens. In the future, the metric used to calculate fairness,
and the proportionality of fairness will be configurable.
Default values for this field will not be set, to allow for future additions of new field that may 'one of' with this field.
Any implementations that may consume this field may treat an unset value as the 'Standard' range. | | Enum: [Critical Standard Sheddable]
| +| `criticality` _[Criticality](#criticality)_ | Criticality defines how important it is to serve the model compared to other models referencing the same pool.
Criticality impacts how traffic is handled in resource constrained situations. It handles this by
queuing or rejecting requests of lower criticality. InferenceModels of an equivalent Criticality will
fairly share resources over throughput of tokens. In the future, the metric used to calculate fairness,
and the proportionality of fairness will be configurable.

Default values for this field will not be set, to allow for future additions of new field that may 'one of' with this field.
Any implementations that may consume this field may treat an unset value as the 'Standard' range. | | Enum: [Critical Standard Sheddable]
| | `targetModels` _[TargetModel](#targetmodel) array_ | TargetModels allow multiple versions of a model for traffic splitting.
If not specified, the target model name is defaulted to the modelName parameter.
modelName is often in reference to a LoRA adapter. | | MaxItems: 10
| | `poolRef` _[PoolObjectReference](#poolobjectreference)_ | PoolRef is a reference to the inference pool, the pool must exist in the same namespace. | | Required: \{\}
| @@ -230,7 +237,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | Conditions track the state of the InferenceModel.
Known condition types are:
* "Accepted" | [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Ready]] | MaxItems: 8
| +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | Conditions track the state of the InferenceModel.

Known condition types are:

* "Accepted" | [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Ready]] | MaxItems: 8
| #### InferencePool @@ -287,7 +294,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | -| `parent` _[PoolStatus](#poolstatus) array_ | Parents is a list of parent resources (usually Gateways) that are
associated with the route, and the status of the InferencePool with respect to
each parent.
A maximum of 32 Gateways will be represented in this list. An empty list
means the route has not been attached to any Gateway. | | MaxItems: 32
| +| `parent` _[PoolStatus](#poolstatus) array_ | Parents is a list of parent resources (usually Gateways) that are
associated with the route, and the status of the InferencePool with respect to
each parent.

A maximum of 32 Gateways will be represented in this list. An empty list
means the route has not been attached to any Gateway. | | MaxItems: 32
| #### Kind @@ -296,13 +303,17 @@ _Underlying type:_ _string_ Kind refers to a Kubernetes Kind. + Valid values include: + * "Service" * "HTTPRoute" + Invalid values include: + * "invalid/kind" - "/" is an invalid character _Validation:_ @@ -324,19 +335,24 @@ _Underlying type:_ _string_ LabelKey was originally copied from: https://github.com/kubernetes-sigs/gateway-api/blob/99a3934c6bc1ce0874f3a4c5f20cafd8977ffcb4/apis/v1/shared_types.go#L694-L731 Duplicated as to not take an unexpected dependency on gw's API. + LabelKey is the key of a label. This is used for validation of maps. This matches the Kubernetes "qualified name" validation that is used for labels. Labels are case sensitive, so: my-label and My-Label are considered distinct. + Valid values include: + * example * example.com * example.com/path * example.com/path.html + Invalid values include: + * example~ - "~" is an invalid character * example.com. - can not start or end with "." @@ -360,8 +376,10 @@ of maps. This matches the Kubernetes label validation rules: * unless empty, must begin and end with an alphanumeric character ([a-z0-9A-Z]), * could contain dashes (-), underscores (_), dots (.), and alphanumerics between. + Valid values include: + * MyValue * my.name * 123-my-value @@ -428,7 +446,7 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `parentRef` _[ObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#objectreference-v1-core)_ | GatewayRef indicates the gateway that observed state of InferencePool. | | | -| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | Conditions track the state of the InferencePool.
Known condition types are:
* "Accepted"
* "ResolvedRefs" | [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted]] | MaxItems: 8
| +| `conditions` _[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.31/#condition-v1-meta) array_ | Conditions track the state of the InferencePool.

Known condition types are:

* "Accepted"
* "ResolvedRefs" | [map[lastTransitionTime:1970-01-01T00:00:00Z message:Waiting for controller reason:Pending status:Unknown type:Accepted]] | MaxItems: 8
| #### PortNumber @@ -467,6 +485,6 @@ _Appears in:_ | Field | Description | Default | Validation | | --- | --- | --- | --- | | `name` _string_ | Name is the name of the adapter or base model, as expected by the ModelServer. | | MaxLength: 253
Required: \{\}
| -| `weight` _integer_ | Weight is used to determine the proportion of traffic that should be
sent to this model when multiple target models are specified.
Weight defines the proportion of requests forwarded to the specified
model. This is computed as weight/(sum of all weights in this
TargetModels list). For non-zero values, there may be some epsilon from
the exact proportion defined here depending on the precision an
implementation supports. Weight is not a percentage and the sum of
weights does not need to equal 100.
If a weight is set for any targetModel, it must be set for all targetModels.
Conversely weights are optional, so long as ALL targetModels do not specify a weight. | | Maximum: 1e+06
Minimum: 1
| +| `weight` _integer_ | Weight is used to determine the proportion of traffic that should be
sent to this model when multiple target models are specified.

Weight defines the proportion of requests forwarded to the specified
model. This is computed as weight/(sum of all weights in this
TargetModels list). For non-zero values, there may be some epsilon from
the exact proportion defined here depending on the precision an
implementation supports. Weight is not a percentage and the sum of
weights does not need to equal 100.

If a weight is set for any targetModel, it must be set for all targetModels.
Conversely weights are optional, so long as ALL targetModels do not specify a weight. | | Maximum: 1e+06
Minimum: 1
| From 1405ff93b25c7e98040ce2fcf2f61e38f6848051 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 09:58:36 -0400 Subject: [PATCH 15/35] change from gh-pages to docs branch --- hack/mkdocs/make-docs.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index 2be6feef0..4ff6665cd 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -104,11 +104,11 @@ make api-ref-docs echo "Deploying docs for version ${VERSION}" if [[ "$VERSION" == "main" ]]; then echo "Deploying docs as 'main'." - mike deploy --push 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 "${VERSION}" 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 "${VERSION}" + mike deploy --push --branch docs "${VERSION}" fi From ff3d933b3ce7edf4690ccc3ee6b788fe0c0da12f Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 09:58:48 -0400 Subject: [PATCH 16/35] Update the release process to include make docs --- .github/ISSUE_TEMPLATE/new-release.md | 4 ++-- Makefile | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/new-release.md b/.github/ISSUE_TEMPLATE/new-release.md index 27e837845..951e339f1 100644 --- a/.github/ISSUE_TEMPLATE/new-release.md +++ b/.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. +1. Update docs in the `main` branch. 2. Close this issue. [repo]: https://github.com/kubernetes-sigs/gateway-api-inference-extension diff --git a/Makefile b/Makefile index bc100b5a0..af861f9de 100644 --- a/Makefile +++ b/Makefile @@ -260,11 +260,13 @@ bbr-image-kind: bbr-image-build ## Build the image and load it to kind cluster $ ##@ Docs +# TODO: I think this can be removed now that we have "make docs" .PHONY: build-docs build-docs: docker build --pull -t gaie/mkdocs hack/mkdocs/image docker run --rm -v ${PWD}:/docs gaie/mkdocs build +# TODO: Update this to use the new docs target .PHONY: build-docs-netlify build-docs-netlify: pip install -r hack/mkdocs/image/requirements.txt @@ -345,8 +347,7 @@ artifacts: kustomize @$(call clean-manifests) .PHONY: release -release: artifacts release-quickstart verify test # Create a release. -# TODO: add a docs target in between release-quickstart and verify +release: artifacts release-quickstart verify test docs # Create a release. ##@ Dependencies From c88ecf656beb0b4e12fe59125b03107ac618d891 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 09:59:08 -0400 Subject: [PATCH 17/35] Add versioning info to contributors guide --- site-src/contributing/docs.md | 46 ++++++++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 11 deletions(-) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index f65121915..a73f5d0a1 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -2,6 +2,8 @@ This doc site is built using MkDocs. It includes a Docker image for you to preview local changes without needing to set up MkDocs and its related plug-ins. +The docs are sourced from the `main` and release branches (such as `release-0.1`). The docs from these branches are then versioned and deployed to the `docs` branch via a tool called `mike`. + ## Preview local changes 1. In the `site-src` directory, make your changes to the Markdown files. @@ -29,7 +31,26 @@ If you need guidance on specific words that are not covered in one of those styl ## Version the docs -The Material theme uses `mike` to version the docs. The following steps cover common workflows for versioning. For more information, see the following resources: +The Material theme uses `mike` to version the docs. + +### Automatic versioning for releases + +The `make docs` target in the Makefile runs the `hack/mkdocs/make-docs.sh` script. This script runs `mike` to version the docs based on the current branch. It works for `main` and major/minor release branches such as `release-0.1`. + +### Update versioned docs + +For main or release branches such as `release-0.1`, you can update doc content as follows: + +1. Check out the main or release branch. +2. Make changes to the markdown files in the `site-src` directory. +3. Run `make docs` to build the docs and push the changes to the `gh-pages` branch. +4. Netlify gets triggered automatically and publishes the changes to the website. + +### Manual versioning + +Sometimes, you might need to manually update a doc version. For example, you might want to delete an old LTS version that is no longer needed. + +The following steps cover common workflows for versioning. For more information, see the following resources: * [Material theme versioning page](https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/) * [`mike` readme](https://github.com/jimporter/mike) @@ -37,6 +58,7 @@ The Material theme uses `mike` to version the docs. The following steps cover co Example workflow for using `mike`: 1. List the current versions. Aliases are included in brackets. + ```sh mike list @@ -46,23 +68,25 @@ Example workflow for using `mike`: 0.1 ``` -2. In the `site-src` directory, make and save your doc changes. +2. Check out the branch that you want to build the docs from. + +3. In the `site-src` directory, make and save your doc changes. -3. Add the changes to the versions that you want to publish them in. The following example adds the changes to both the latest 0.2 and 0.3 main versions. +4. Add the changes to the versions that you want to publish them in. If the version has an alias such as latest, you can include that. + ```sh - mike deploy --push --update-aliases 0.3 main - mike deploy --push --update-aliases 0.2 latest + mike deploy --push --update-aliases 0.4 latest ``` -4. Optional: Add a new version of the docs. The following example adds a new version 0.4 as main based on the current content, renames 0.3 to latest with the current content, removes the latest alias from 0.2 but leaves the version content untouched, and deletes version 0.1. +5. Delete an old version of the docs that you no longer need. The following example adds a new version 0.4 as main based on the current content, renames 0.3 to latest with the current content, removes the latest alias from 0.2 but leaves the version content untouched, and deletes version 0.1. + ```sh - mike delete latest - mike deploy --push --update-aliases 0.4 main - mike deploy --push --update-aliases 0.3 latest mike delete 0.1 ``` -The `mike` commands add each version as a separate commit and directory on the `gh-pages` branch. +### How versioning works + +The `mike` commands add each version as a separate commit and directory on the `docs` branch. * The versioned directories contain the output of the MkDocs build for each version. * The `latest` and `main` aliases are copies of the versioned directories. @@ -71,7 +95,7 @@ The `mike` commands add each version as a separate commit and directory on the ` Example directory structure: ```plaintext -gh-pages branch +'docs' branch │── 0.1/ │── 0.2/ │── 0.3/ From fd463f137db1b6a840e9647e3129f5e302438338 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 10:00:45 -0400 Subject: [PATCH 18/35] update mike serve for docs branch --- Makefile | 2 +- hack/mkdocs/image/entrypoint.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index af861f9de..1d75953f4 100644 --- a/Makefile +++ b/Makefile @@ -287,7 +287,7 @@ docs: crd-ref-docs ## Deploy documentation using mike, determining latest versio .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 mike serve -a 0.0.0.0:3000 + 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: diff --git a/hack/mkdocs/image/entrypoint.sh b/hack/mkdocs/image/entrypoint.sh index 45b78cd24..3a85df2b1 100755 --- a/hack/mkdocs/image/entrypoint.sh +++ b/hack/mkdocs/image/entrypoint.sh @@ -26,4 +26,4 @@ then fi # Use mike serve for versioning support -mike serve -a 0.0.0.0:3000 \ No newline at end of file +mike serve -a 0.0.0.0:3000 --branch docs \ No newline at end of file From dea46d3e2bb6e667b410b5d4a8741932863a8123 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 10:08:51 -0400 Subject: [PATCH 19/35] Update docs guide --- site-src/contributing/docs.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index a73f5d0a1..1299e05b5 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -2,7 +2,11 @@ This doc site is built using MkDocs. It includes a Docker image for you to preview local changes without needing to set up MkDocs and its related plug-ins. -The docs are sourced from the `main` and release branches (such as `release-0.1`). The docs from these branches are then versioned and deployed to the `docs` branch via a tool called `mike`. +Branch sources of the docs content: + +- `main` branch for `main` version +- `release-MAJOR.MINOR` branches such as `release-0.1` for `0.1` version +- `docs` branch for the versioned directories that are published via Netlify to the website ## Preview local changes @@ -58,7 +62,6 @@ The following steps cover common workflows for versioning. For more information, Example workflow for using `mike`: 1. List the current versions. Aliases are included in brackets. - ```sh mike list @@ -72,14 +75,13 @@ Example workflow for using `mike`: 3. In the `site-src` directory, make and save your doc changes. -4. Add the changes to the versions that you want to publish them in. If the version has an alias such as latest, you can include that. - +4. Add the changes to the versions that you want to publish them in. If the version has an alias such as latest, you can include that. Make sure to include the `--branch docs` flag, so as not to publish docs to the `mike` default `gh-pages` branch. ```sh - mike deploy --push --update-aliases 0.4 latest + mike deploy --push --branch docs main + mike deploy --push --update-aliases 0.4 --branch docs latest ``` 5. Delete an old version of the docs that you no longer need. The following example adds a new version 0.4 as main based on the current content, renames 0.3 to latest with the current content, removes the latest alias from 0.2 but leaves the version content untouched, and deletes version 0.1. - ```sh mike delete 0.1 ``` From b359ab20f16f430fd3a3c0498a4751c0315f8604 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 10:21:08 -0400 Subject: [PATCH 20/35] Update Netlify settings and remove old make commands --- Makefile | 12 ------------ netlify.toml | 10 +++++++--- 2 files changed, 7 insertions(+), 15 deletions(-) diff --git a/Makefile b/Makefile index 1d75953f4..583060027 100644 --- a/Makefile +++ b/Makefile @@ -260,18 +260,6 @@ bbr-image-kind: bbr-image-build ## Build the image and load it to kind cluster $ ##@ Docs -# TODO: I think this can be removed now that we have "make docs" -.PHONY: build-docs -build-docs: - docker build --pull -t gaie/mkdocs hack/mkdocs/image - docker run --rm -v ${PWD}:/docs gaie/mkdocs build - -# TODO: Update this to use the new docs target -.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 || { \ diff --git a/netlify.toml b/netlify.toml index ff61e3bfc..e7f693fb8 100644 --- a/netlify.toml +++ b/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" } \ No newline at end of file +environment.PYTHON_VERSION = "3.8" + +# Specify that we want to build from the docs branch +[context.production] + branch = "docs" \ No newline at end of file From bba0257a0a0014ee7d8d12e07216eaf703f09672 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 10:51:40 -0400 Subject: [PATCH 21/35] update regex in case release doesn't have v or has extra info after patch --- hack/mkdocs/make-docs.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index 4ff6665cd..f64e6d466 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -58,8 +58,8 @@ is_latest_version() { return 1 fi - # Extract version from tag (e.g., v0.3.0 -> 0.3) - if [[ $latest_tag =~ v([0-9]+)\.([0-9]+)\. ]]; then + # 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]}" From 4a6789a010bfe7c6677a11809044abbe109fddd2 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Fri, 23 May 2025 10:58:37 -0400 Subject: [PATCH 22/35] Update publish process --- site-src/contributing/docs.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index 1299e05b5..dc60d0905 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -137,12 +137,4 @@ General steps: ## Publish the docs -The project uses Netlify to host the docs. - -You can locally build the files that become the doc site. For example, you might want to check the HTML output of changes that you make to the site. - -```sh -make build-docs-netlify -``` - -The Gateway API Inference Extension team will publish the docs based on the latest changes in the `main` branch. \ No newline at end of file +The project uses Netlify to host the docs. Netlify automatically builds the docs based on the versioned directories in the `docs` branch. From 0033ef371d02cea68a6dc384b16e70ddbef9ed00 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 27 May 2025 11:54:21 -0400 Subject: [PATCH 23/35] fix branch name in description --- site-src/contributing/docs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site-src/contributing/docs.md b/site-src/contributing/docs.md index dc60d0905..25809b202 100644 --- a/site-src/contributing/docs.md +++ b/site-src/contributing/docs.md @@ -47,7 +47,7 @@ For main or release branches such as `release-0.1`, you can update doc content a 1. Check out the main or release branch. 2. Make changes to the markdown files in the `site-src` directory. -3. Run `make docs` to build the docs and push the changes to the `gh-pages` branch. +3. Run `make docs` to build the docs and push the changes to the `docs` branch. 4. Netlify gets triggered automatically and publishes the changes to the website. ### Manual versioning From 8e9f3d8b01373985632642a2e6f2681c796395e4 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 27 May 2025 12:16:28 -0400 Subject: [PATCH 24/35] Set default version to latest So that the banner works to send users from main or old branches to latest --- hack/mkdocs/image/entrypoint.sh | 2 ++ hack/mkdocs/make-docs.sh | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/hack/mkdocs/image/entrypoint.sh b/hack/mkdocs/image/entrypoint.sh index 3a85df2b1..32214904a 100755 --- a/hack/mkdocs/image/entrypoint.sh +++ b/hack/mkdocs/image/entrypoint.sh @@ -22,6 +22,8 @@ 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 diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index f64e6d466..21dca6b13 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -112,3 +112,7 @@ 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 From 992b3a7cad5fb4aca73a98fac717cefd7019a863 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 27 May 2025 12:35:05 -0400 Subject: [PATCH 25/35] Update deploy step So that latest is copied and actually available as a url /latest/ and not just the version, like /0.3/ --- hack/mkdocs/make-docs.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index 21dca6b13..bd04682f1 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -107,7 +107,7 @@ if [[ "$VERSION" == "main" ]]; then 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 + 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}" From 29652fa86a5c25aab891a92c62d65fb4c0d675a8 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Tue, 27 May 2025 13:29:13 -0400 Subject: [PATCH 26/35] update release --- .github/ISSUE_TEMPLATE/new-release.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/new-release.md b/.github/ISSUE_TEMPLATE/new-release.md index 951e339f1..507d8fa97 100644 --- a/.github/ISSUE_TEMPLATE/new-release.md +++ b/.github/ISSUE_TEMPLATE/new-release.md @@ -149,8 +149,7 @@ Use the following steps to announce the release. ## Final Steps -1. Update docs in the `main` branch. -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 From f20984f26136c60452f8dd4e88a7e2d9533b270e Mon Sep 17 00:00:00 2001 From: Art Berger Date: Thu, 29 May 2025 14:24:36 -0400 Subject: [PATCH 27/35] update netlify.toml to match settings in Netlify --- netlify.toml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/netlify.toml b/netlify.toml index e7f693fb8..dea96d41d 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,9 +1,13 @@ # netlify configuration [build] -publish = "." -command = "" -# 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] From dccb488ac405e30dea940fd92e9d0fc269d48756 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 09:35:02 -0400 Subject: [PATCH 28/35] change crd-ref-docs to be like Gateway API similar to https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/mkdocs/generate.sh also to address peer review feedback about dependency install --- .gitignore | 2 +- hack/mkdocs/make-docs.sh | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 237f2fbd4..f259fa3df 100644 --- a/.gitignore +++ b/.gitignore @@ -32,4 +32,4 @@ go.work.sum site # virtual environment for mkdocs -.venv \ No newline at end of file +.venv diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index bd04682f1..822b75dd4 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -98,7 +98,23 @@ run::sed() { # ----------------------------------------------------------------------------- # Generate API docs -make api-ref-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}/apis \ + --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}" From 82cb3148e911997e54c1a2d9abce24afcde6e592 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 09:36:18 -0400 Subject: [PATCH 29/35] rm crd-ref-docs from makefile --- Makefile | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/Makefile b/Makefile index 583060027..935d43d6f 100644 --- a/Makefile +++ b/Makefile @@ -260,15 +260,9 @@ bbr-image-kind: bbr-image-build ## Build the image and load it to kind cluster $ ##@ Docs -.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. +docs: ## Deploy documentation using mike, determining latest version from git tags. chmod +x ./hack/mkdocs/make-docs.sh ./hack/mkdocs/make-docs.sh From 5f26e560248054fee3ded6dbb6636f0927cfcb59 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 09:40:00 -0400 Subject: [PATCH 30/35] rm api-ref-docs target and fix path --- Makefile | 8 -------- hack/mkdocs/make-docs.sh | 2 +- 2 files changed, 1 insertion(+), 9 deletions(-) diff --git a/Makefile b/Makefile index 935d43d6f..a379f697d 100644 --- a/Makefile +++ b/Makefile @@ -271,14 +271,6 @@ live-docs: docker build -t gaie/mkdocs hack/mkdocs/image 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: - 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. # diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index 822b75dd4..a4c98a4e2 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -111,7 +111,7 @@ echo $GOBIN go install github.com/elastic/crd-ref-docs ${GOBIN}/crd-ref-docs \ - --source-path=${PWD}/apis \ + --source-path=${PWD}/api \ --config=crd-ref-docs.yaml \ --renderer=markdown \ --output-path=${PWD}/site-src/reference/spec.md From facd79074f7dcb54101db7e6d0dda6c891420244 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 09:45:27 -0400 Subject: [PATCH 31/35] fix latest tagging was tagging as latest if equal or greater than the release marked latest --- hack/mkdocs/make-docs.sh | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index a4c98a4e2..555121ed0 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -49,31 +49,31 @@ get_version_from_branch() { # Check if version should be marked as latest # ----------------------------------------------------------------------------- is_latest_version() { - # Get the latest release tag, checking more releases to find the true latest + # Get the latest release tag 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 + local latest_version="${latest_major}.${latest_minor}" + + # Only return 0 (true) if the current version matches the latest version exactly + if [[ "$VERSION" == "$latest_version" ]]; then + return 0 fi else echo "Error: Could not parse version from latest tag: $latest_tag" return 1 fi - - return 1 # Current version is older + + return 1 } # Get version from current branch From d16365ce564fc9b4010bbf1d42f915b82696de48 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 09:48:49 -0400 Subject: [PATCH 32/35] fix latest --- hack/mkdocs/make-docs.sh | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index 555121ed0..94a0e8ffb 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -62,10 +62,8 @@ is_latest_version() { if [[ $latest_tag =~ ^v?([0-9]+)\.([0-9]+)(\.[0-9]+)?$ ]]; then local latest_major="${BASH_REMATCH[1]}" local latest_minor="${BASH_REMATCH[2]}" - local latest_version="${latest_major}.${latest_minor}" - # Only return 0 (true) if the current version matches the latest version exactly - if [[ "$VERSION" == "$latest_version" ]]; then + if [[ "$MAJOR" -eq "$latest_major" && "$MINOR" -eq "$latest_minor" ]]; then return 0 fi else From deb833046ea38f78003fe0f70a8fe7c805e3ca1a Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 10:04:00 -0400 Subject: [PATCH 33/35] update mike server commands duplicate from the entrypoint.sh for the docker image --- Makefile | 2 +- hack/mkdocs/image/entrypoint.sh | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index a379f697d..af0ef8771 100644 --- a/Makefile +++ b/Makefile @@ -269,7 +269,7 @@ docs: ## Deploy documentation using mike, determining latest version from git ta .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 mike serve -a 0.0.0.0:3000 --branch docs + docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gaie/mkdocs # Generate a virtualenv install, which is useful for hacking on the # docs since it installs mkdocs and all the right dependencies. diff --git a/hack/mkdocs/image/entrypoint.sh b/hack/mkdocs/image/entrypoint.sh index 32214904a..94faa23cc 100755 --- a/hack/mkdocs/image/entrypoint.sh +++ b/hack/mkdocs/image/entrypoint.sh @@ -28,4 +28,4 @@ then fi # Use mike serve for versioning support -mike serve -a 0.0.0.0:3000 --branch docs \ No newline at end of file +mike serve -a 0.0.0.0:3000 --branch docs From a89269823635fad62570d287e7bd981e883fab75 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 10:17:28 -0400 Subject: [PATCH 34/35] change from gh to git --- hack/mkdocs/make-docs.sh | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/hack/mkdocs/make-docs.sh b/hack/mkdocs/make-docs.sh index 94a0e8ffb..a566c4d4f 100755 --- a/hack/mkdocs/make-docs.sh +++ b/hack/mkdocs/make-docs.sh @@ -46,31 +46,36 @@ get_version_from_branch() { } # ----------------------------------------------------------------------------- -# Check if version should be marked as latest +# Check if version should be marked as latest (ignore release candidates "-rc" or any hyphenated suffix) # ----------------------------------------------------------------------------- is_latest_version() { - # Get the latest release tag + # 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=$(gh release list --limit 20 --json tagName --jq '.[0].tagName') + 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 releases." + echo "Error: Could not find any semver‐style tags." 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 + # 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 "-" (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]}" - # Only return 0 (true) if the current version matches the latest version exactly - if [[ "$MAJOR" -eq "$latest_major" && "$MINOR" -eq "$latest_minor" ]]; then - return 0 - fi else - echo "Error: Could not parse version from latest tag: $latest_tag" + 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 } From 77612a01586e40e8e10323b43f6166105d51e172 Mon Sep 17 00:00:00 2001 From: Art Berger Date: Wed, 4 Jun 2025 10:19:31 -0400 Subject: [PATCH 35/35] add line --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index dea96d41d..e6167fd26 100644 --- a/netlify.toml +++ b/netlify.toml @@ -11,4 +11,4 @@ # Specify that we want to build from the docs branch [context.production] - branch = "docs" \ No newline at end of file + branch = "docs"