[WIP] Add versioning to the docs #869

artberger · 2025-05-23T15:13:53Z

Addresses #422

Summary of changes

Updates the doc publishing process to add versioning capability. The docs are versioned using a MkDocs plug-in called mike (GitHub project here).

Right now, I have the versioned docs working locally based off my fork in Netlify here: https://adb-inf-extension.netlify.app/main/

Overview of the new process:

A make-docs.sh script is added to run mike to build versioned docs based on the branch, such as main or a release branch like release-0.1. This script is turned into a make target, which is also called as part of the release process.
When the script runs, mike builds the HTML files for the version based on the content in that branch.
The versioned files are then put in their own directories on a docs branch.
Netlify is updated to build automatically based on changes to the docs branch.

The versioned process is described in a Docs Contribution guide that is added in this PR. This way, people can see how the versioning process works, and manually update it if needed (such as to delete an old version). See preview: https://adb-inf-extension.netlify.app/main/contributing/docs/#version-the-docs

Order of steps to update the docs publishing process

Step 1: Before merging this PR, create the docs branch.

You have to do a one-time creation of a clean docs branch so that the mike tool can put the versioned docs on that branch.

Locally, I used the following commands to do that:

git checkout --orphan docs
git rm -rf .
git clean -fdx
git commit --allow-empty -m "Initial commit of docs"
git push origin docs

Step 2: Merge this PR

One caveat is, the Netlify builds will fail on this PR unless we change Netlify first (see the Netlify section). I think it would keep the currently published content on the GIE URL until it has new content to replace it with, but I am not sure.

Step 3: Copy the netlify.toml file to the docs branch

We might have to copy this to the docs branch, I am not sure how the Netlify is set up in this repo. By putting it on the docs branch, the publishing branch has the Netlify settings so we wouldn't have to update the Netlify settings in the UI (see section later).

Step 4: Build versioned docs to the docs branch.

To build the versioned docs, we would check out each branch (main, the release branches) and run make docs.

Netlify considerations

I am not sure who or how the GIE Netlify is currently set up.

In my Netlify account, I have the following settings. These are reflected in the netlify.toml that we would need to add to the docs branch.

This way, Netlify builds based on changes to the docs branch. You don't need a specific build command because the HTML files are already built to the docs branch through the mike versioning.

Build & Deploy > Build settings

Runtime: Not set
Base directory: /
Package directory: Not set
Build command: Not set
Publish directory: .

Build & Deploy > Branches and deploy contexts

Production branch: docs

Fixes #422

the previous /images/ does not work when the content is versioned

otherwise, it did not appear because its in the same header_topic element that was getting hidden

Based on Gateway API https://github.com/kubernetes-sigs/gateway-api/blob/main/Makefile#L162-L172

in case release doesn't have v or has extra info after patch

netlify · 2025-05-23T15:13:59Z

❌ Deploy Preview for gateway-api-inference-extension failed. Why did it fail? →

Name	Link
🔨 Latest commit	`77612a0`
🔍 Latest deploy log	https://app.netlify.com/projects/gateway-api-inference-extension/deploys/684055f906ea7400071826a0

k8s-ci-robot · 2025-05-23T15:14:01Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: artberger
Once this PR has been reviewed and has the lgtm label, please assign danehans for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2025-05-23T15:14:03Z

Welcome @artberger!

It looks like this is your first PR to kubernetes-sigs/gateway-api-inference-extension 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/gateway-api-inference-extension has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

robscott · 2025-05-28T22:07:41Z

@robscott PTAL at the approach that is being used here for docs versioning. If you agree with this approach and have access to the GIE Netlify project, can you tackle step 4?

As a side note, does anyone else have access to the GIE Netlify project?

Unfortunately I don't have access to Netlify here. I think there's a small set of admins that control Netlify for all Kubernetes projects. Maybe #github-management Slack channel would have an answer. In the past, @mrbobbytables has helped us get Netlify setup.

Just to clarify, is the problem that these changes can't be configured in netlify.toml alone and instead require higher level changes?

artberger · 2025-05-29T13:50:30Z

@robscott thanks for the information. I was not sure how the GIE project's Netlify worked, and so I was sharing how I got it working for my forked repo and the GIE Netlify project I set up in my personal Netlify account.

Update: I updated the netlify.toml file to mirror the settings that I have in my Netlify account. This file would go on the docs branch. I believe the Netlify builds on this PR are failing because they still expect things to be the "old way," such as looking for a site directory like the error message mentions.

to match settings in Netlify

danehans · 2025-06-02T16:14:31Z

.gitignore

@@ -30,3 +30,6 @@ go.work.sum

 # generated docs
 site
+
+# virtual environment for mkdocs
+.venv


nit: Add new line

danehans · 2025-06-02T16:35:36Z

netlify.toml

+# Specify that we want to build from the docs branch
+[context.production]
+  branch = "docs"


nit: New blank line

danehans · 2025-06-02T17:10:26Z

Makefile


 .PHONY: live-docs
 live-docs:
 	docker build -t gaie/mkdocs hack/mkdocs/image
-	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gaie/mkdocs
+	docker run --rm -it -p 3000:3000 -v ${PWD}:/docs gaie/mkdocs mike serve -a 0.0.0.0:3000 --branch docs


This change should not be required since it's implemented in entrypoint.sh. Can you remove and test?

This target fails when using your branch:

make live-docs docker build -t gaie/mkdocs hack/mkdocs/image [+] Building 0.5s (11/11) FINISHED => [internal] load build definition from Dockerfile 0.0s => => transferring dockerfile: 886B 0.0s => [internal] load .dockerignore 0.0s => => transferring context: 2B 0.0s => [internal] load metadata for docker.io/library/python:3.13-alpine 0.4s => [internal] load build context 0.0s => => transferring context: 1.55kB 0.0s => [1/6] FROM docker.io/library/python:3.13-alpine@sha256:a94caf6aab428e086bc398beaf64a6b7a0fad4589573462f52362fd760e64cc9 0.0s => CACHED [2/6] RUN apk add --no-cache git 0.0s => CACHED [3/6] COPY requirements.txt /requirements.txt 0.0s => CACHED [4/6] RUN pip install -r /requirements.txt 0.0s => CACHED [5/6] WORKDIR /docs 0.0s => CACHED [6/6] COPY entrypoint.sh / 0.0s => exporting to image 0.0s => => exporting layers 0.0s => => writing image sha256:3d3d10a2a4a520efc0ef0fc01e1aabb39b5911762e0226b637b2f80f56ce66b7 0.0s => => naming to docker.io/gaie/mkdocs 0.0s Use 'docker scan' to run Snyk tests against images to find vulnerabilities and learn how to fix them docker run --rm -it -p 3000:3000 -v /Users/solo-system-dhansen/go/src/sigs.k8s.io/gateway-api-inference-extension:/docs gaie/mkdocs mike serve -a 0.0.0.0:3000 --branch docs Config value 'plugins': Plugin 'macros' option 'j2_line_comment_prefix': Unrecognised configuration name: j2_line_comment_prefix Starting server at http://0.0.0.0:3000/ Press Ctrl+C to quit. 172.17.0.1 - - [02/Jun/2025 18:01:58] code 404, message File not found. Did you forget to run `mike set-default`? Alternately, you can navigate to 36fe7b09f30a:3000/[some-version] to see your docs 172.17.0.1 - - [02/Jun/2025 18:01:58] "GET / HTTP/1.1" 404 -

Note that I see WARNING - Config value 'plugins': Plugin 'macros' option 'j2_line_comment_prefix': Unrecognised configuration name: j2_line_comment_prefix using the main branch so that is not the root case.

I removed the mike serve -a 0.0.0.0:3000 --branch docs line, and was able to run the target.

For the error you saw:

code 404, message File not found. Did you forget to run mike set-default? Alternately, you can navigate to 36fe7b09f30a:3000/[some-version] to see your docs

The entrypoint.sh now sets a default version. I think the duplicate mike serve command that I removed was throwing it off and since you didn't have a default set locally, it was throwing that error.

danehans · 2025-06-02T17:30:31Z

Makefile

+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; \
+	}


I get the following error when calling this target (MacOS):

Installing crd-ref-docs... chmod +x ./hack/mkdocs/make-docs.sh ... bash: line 1: crd-ref-docs: command not found make[1]: *** [api-ref-docs] Error 127 make: *** [docs] Error 2

Can you take a look at how the other dependencies are installed and follow the same pattern? Make sure to use a tagged release instead of latest.

After resolving ^ issue, I now hit the following issue:

$ make docs chmod +x ./hack/mkdocs/make-docs.sh ... Error: Could not find any releases. This version will be deployed, but not marked as 'latest'. ./hack/mkdocs/make-docs.sh: line 113: mike: command not found make: *** [docs] Error 127

To avoid these local deps issues, why not run ./hack/mkdocs/make-docs.sh in the Docker container instead of locally?

Thanks for pointing out the crd-ref-docs issue. I removed these from the Makefile and instead put it in the make-docs.sh similar to how the Gateway API project does it here: https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/mkdocs/generate.sh

To avoid these local deps issues, why not run ./hack/mkdocs/make-docs.sh in the Docker container instead of locally?

So I might be misunderstanding this, but the Docker container I thought was just to make the local preview of the docs. If we run the make-docs script in the container, I think it would build and push the docs each time someone ran the container for a local preview, which might not be what we wanted.

danehans · 2025-06-02T18:12:22Z

hack/mkdocs/image/entrypoint.sh

  exit 0;
 fi

-mkdocs serve --dev-addr=0.0.0.0:3000 --livereload


Does mike serve support --livereload by default?

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

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

danehans · 2025-06-02T18:23:45Z

Makefile

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


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.

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)

similar to https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/mkdocs/generate.sh also to address peer review feedback about dependency install

was tagging as latest if equal or greater than the release marked latest

duplicate from the entrypoint.sh for the docker image

danehans · 2025-06-09T17:14:52Z

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


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

danehans · 2025-06-09T17:17:42Z

mkdocs.yml

 docs_dir: site-src
+extra:
+  version:
+    provider: mike


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

@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

k8s-ci-robot · 2025-06-10T21:27:08Z

PR needs rebase.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

kfswain · 2025-06-23T20:34:15Z

Is there anyone we need to chase down to unblock this? I saw a comment saying we are blocked somewhere

danehans · 2025-06-23T23:30:59Z

@kfswain @artberger see #422 (comment). TLDR is I believe a CI job may be needed to implement docs versioning. @artberger I can create a docs branch in the repo if you would like to test your workflow. WDYT?

artberger · 2025-06-25T12:52:58Z

@kfswain for what is blocking this PR, the Netlify CI checks are failing. I believe this is to be expected, because the PR changes this netlify.toml file. The change is to make Netlify build the content from a docs branch with separate directories per version, so it no longer uses the site directory on main branch that the CI checks expect, and hence the PR fails those checks.

However, I haven't gotten a response about who would know to confirm the Netlify changes and whether we can change the checks for the new approach vs the existing one (Slack post).

@danehans I will look more into your approach of using a GitHub Action later today to see whether I can revise this PR to use that approach. From my initial review, I couldn't tell where mike was making the branch with versioned content, or how to update LTS docs moving forward from that approach. Also it looks like your PR also failed the same Netlify CI checks, so I think that would still be an issue.

danehans · 2025-06-27T18:54:19Z

I couldn't tell where mike was making the branch with versioned content

My approach intends to use the main or release branch instead of a separate branch for the versioned docs. I'm not against using your docs branch approach; it was just a different approach that I wanted to try.

artberger · 2025-08-01T13:04:19Z

I'm going to close this PR, since the last update I had was that we wanted to use a GitHub Actions instead of a make command approach. I have a draft of those changes in a fork / preview site, see comment.

artberger added 23 commits March 3, 2025 14:58

contribution guide updates

1fd0314

image path relative

dbc3b22

the previous /images/ does not work when the content is versioned

mike versioning

7d8ecde

update doc guide

ed87f3f

period

c49b44d

ensure version switcher remains visible

d313861

otherwise, it did not appear because its in the same header_topic element that was getting hidden

fix formattin

196be29

fix location of main.html in overrides

385f50d

Add make virtual environment command

5769e8f

Based on Gateway API https://github.com/kubernetes-sigs/gateway-api/blob/main/Makefile#L162-L172

add link to localhost

f290f5f

add warning

a13e744

Add versioning to local docker image

7e68026

Merge branch 'main' into adb-versioning

fa32888

revert img update

2f26413

make docs target and make-docs.sh script

fa00351

change from gh-pages to docs branch

1405ff9

Update the release process to include make docs

ff3d933

Add versioning info to contributors guide

c88ecf6

update mike serve for docs branch

fd463f1

Update docs guide

dea46d3

Update Netlify settings and remove old make commands

b359ab2

update regex

bba0257

in case release doesn't have v or has extra info after patch

Update publish process

4a6789a

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label May 23, 2025

k8s-ci-robot requested review from danehans and nirrozenbaum May 23, 2025 15:14

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label May 23, 2025

update netlify.toml

f20984f

to match settings in Netlify

danehans reviewed Jun 2, 2025

View reviewed changes

artberger added 8 commits June 4, 2025 09:35

change crd-ref-docs to be like Gateway API

dccb488

similar to https://github.com/kubernetes-sigs/gateway-api/blob/main/hack/mkdocs/generate.sh also to address peer review feedback about dependency install

rm crd-ref-docs from makefile

82cb314

rm api-ref-docs target and fix path

5f26e56

fix latest tagging

facd790

was tagging as latest if equal or greater than the release marked latest

fix latest

d16365c

update mike server commands

deb8330

duplicate from the entrypoint.sh for the docker image

change from gh to git

a892698

add line

77612a0

artberger mentioned this pull request Jun 6, 2025

Docs versioning #422

Open

danehans reviewed Jun 9, 2025

View reviewed changes

danehans mentioned this pull request Jun 9, 2025

NO NOT MERGE: Versioned docs #944

Closed

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 10, 2025

kfswain changed the title ~~Add versioning to the docs~~ [WIP] Add versioning to the docs Jun 16, 2025

artberger closed this Aug 1, 2025

[WIP] Add versioning to the docs #869

[WIP] Add versioning to the docs #869

Uh oh!

Conversation

artberger commented May 23, 2025 • edited by danehans Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary of changes

Order of steps to update the docs publishing process

Netlify considerations

Uh oh!

netlify bot commented May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Deploy Preview for gateway-api-inference-extension failed. Why did it fail? →

Uh oh!

k8s-ci-robot commented May 23, 2025

Uh oh!

k8s-ci-robot commented May 23, 2025

Uh oh!

robscott commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

artberger commented May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danehans Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danehans Jun 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Jun 10, 2025

Uh oh!

kfswain commented Jun 23, 2025

Uh oh!

danehans commented Jun 23, 2025

Uh oh!

artberger commented Jun 25, 2025

Uh oh!

danehans commented Jun 27, 2025

Uh oh!

artberger commented Aug 1, 2025

Uh oh!

Uh oh!

artberger commented May 23, 2025 •

edited by danehans

Loading

netlify bot commented May 23, 2025 •

edited

Loading

robscott commented May 28, 2025 •

edited

Loading

artberger commented May 29, 2025 •

edited

Loading

danehans Jun 2, 2025 •

edited

Loading

danehans Jun 2, 2025 •

edited

Loading