Skip to content

Add versioning to the docs #869

New issue

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

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

Already on GitHub? Sign in to your account

Draft
wants to merge 36 commits into
base: main
Choose a base branch
from

Conversation

artberger
Copy link

@artberger artberger commented May 23, 2025

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:

  1. 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.
  2. When the script runs, mike builds the HTML files for the version based on the content in that branch.
  3. The versioned files are then put in their own directories on a docs branch.
  4. 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

@k8s-ci-robot 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
Copy link

netlify bot commented May 23, 2025

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
Copy link
Contributor

[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:

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 k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label May 23, 2025
@k8s-ci-robot
Copy link
Contributor

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. 😃

@k8s-ci-robot k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label May 23, 2025
@k8s-ci-robot
Copy link
Contributor

Hi @artberger. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

@k8s-ci-robot k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label May 23, 2025
artberger added 3 commits May 27, 2025 11:54
So that the banner works to send users from main or old branches to latest
So that latest is copied and actually available as a url /latest/ and not just the version, like /0.3/
@danehans danehans requested a review from robscott May 27, 2025 17:08
Copy link
Author

@artberger artberger left a comment

Choose a reason for hiding this comment

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

Adding context to the changes

@@ -66,7 +66,7 @@ This document defines the process for releasing Gateway API Inference Extension.
git checkout -b release-${MAJOR}.${MINOR} ${REMOTE}/release-${MAJOR}.${MINOR}
```

4. Update release-specific content, generate release artifacts, and stage the changes.
4. Update release-specific content, generate release artifacts, build the versioned docs, and stage the changes.
Copy link
Author

Choose a reason for hiding this comment

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

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

@@ -283,6 +285,18 @@ api-ref-docs:
--renderer=markdown \
--output-path=${PWD}/site-src/reference/spec.md

# Generate a virtualenv install, which is useful for hacking on the
Copy link
Author

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Author

Choose a reason for hiding this comment

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

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

wdyt?

Makefile Outdated
build-docs-netlify:
pip install -r hack/mkdocs/image/requirements.txt
python -m mkdocs build
.PHONY: crd-ref-docs
Copy link
Author

Choose a reason for hiding this comment

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

Removed unused doc targets and added new docs target to run the new make-docs script

Copy link
Contributor

Choose a reason for hiding this comment

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

@@ -321,7 +335,7 @@ artifacts: kustomize
@$(call clean-manifests)

.PHONY: release
release: artifacts release-quickstart verify test # Create a release.
release: artifacts release-quickstart verify test docs # Create a release.
Copy link
Author

Choose a reason for hiding this comment

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

Added docs to the release target

# Use mike serve for versioning support
mike serve -a 0.0.0.0:3000 --branch docs
Copy link
Author

Choose a reason for hiding this comment

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

Updated the image for local preview to use the versioning

Copy link
Contributor

Choose a reason for hiding this comment

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

nit: Add new blank line

@@ -0,0 +1,118 @@
#!/bin/bash
Copy link
Author

@artberger artberger May 27, 2025

Choose a reason for hiding this comment

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

The make-docs.sh script

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

Copy link
Author

Choose a reason for hiding this comment

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

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

Copy link
Contributor

@danehans danehans Jun 2, 2025

Choose a reason for hiding this comment

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

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

# -----------------------------------------------------------------------------
# Check if version should be marked as latest (ignore release candidates "-rc" or any hyphenated suffix)
# -----------------------------------------------------------------------------
is_latest_version() {
    # 1) List all tags matching semver-ish (vX.Y[.Z] or X.Y[.Z]), sort by version descending,
    #    and pick the very first one.
    local latest_tag
    latest_tag=$(
      git tag --list 'v[0-9]*.[0-9]*' \
             --list '[0-9]*.[0-9]*'   \
             --sort=-v:refname | head -n1
    )

    if [[ -z "$latest_tag" ]]; then
        echo "Error: Could not find any semver‐style tags."
        return 1
    fi

    # 2) Strip leading 'v', then drop anything after the first hyphen (e.g. "0.3.0-rc.1" → "0.3.0")
    local bare="${latest_tag#v}"       # remove leading "v" if present
    bare="${bare%%-*}"                 # drop "-<anything>" (so "0.3.0-rc.1" → "0.3.0")

    # 3) Now extract MAJOR and MINOR from e.g. "0.3.0" or "2.5"
    if [[ "$bare" =~ ^([0-9]+)\.([0-9]+)(\.[0-9]+)?$ ]]; then
        local latest_major="${BASH_REMATCH[1]}"
        local latest_minor="${BASH_REMATCH[2]}"
    else
        echo "Error: Could not parse version from latest tag: ${latest_tag} (bare='${bare}')"
        return 1
    fi

    # 4) Compare numeric MAJOR/MINOR
    #    If branch’s MAJOR > latest_major, or (MAJOR == latest_major && MINOR ≥ latest_minor), it’s “latest” or newer.
    if (( MAJOR > latest_major )) || \
       (( MAJOR == latest_major && MINOR >= latest_minor )); then
        return 0
    fi

    return 1
}

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

Copy link
Author

Choose a reason for hiding this comment

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

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

netlify.toml Outdated
@@ -1,6 +1,10 @@
# netlify configuration
[build]
publish = "site"
command = "make build-docs-netlify"
publish = "."
Copy link
Author

Choose a reason for hiding this comment

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

Instead of building off updates to main and running the old make command, now Netlify:

  • builds of docs branch
  • publishes the content on the docs branch for all the versioned folders, not just the site folder
  • doesn't need to run a build command, because mike already builds the content to HTML files in the docs branch

@@ -0,0 +1,140 @@
# Contributing to the docs
Copy link
Author

Choose a reason for hiding this comment

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

Added a contributors guide for the docs that outlines the versioning process as well as other things like local preview

@@ -0,0 +1,8 @@
{% extends "base.html" %}
Copy link
Author

Choose a reason for hiding this comment

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

This adds a banner on versions that aren't latest, to point users to latest in case they don't intend to be on this other branch.

@danehans
Copy link
Contributor

@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?

@robscott
Copy link
Member

robscott commented May 28, 2025

@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
Copy link
Author

artberger commented May 29, 2025

@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
.gitignore Outdated
@@ -30,3 +30,6 @@ go.work.sum

# generated docs
site

# virtual environment for mkdocs
.venv
Copy link
Contributor

Choose a reason for hiding this comment

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

nit: Add new line

netlify.toml Outdated
# Specify that we want to build from the docs branch
[context.production]
branch = "docs"
Copy link
Contributor

Choose a reason for hiding this comment

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

nit: New blank line

Makefile Outdated

.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
Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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.

Copy link
Author

Choose a reason for hiding this comment

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

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

Copy link
Author

Choose a reason for hiding this comment

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

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.

Makefile Outdated
Comment on lines 264 to 268
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; \
}
Copy link
Contributor

@danehans danehans Jun 2, 2025

Choose a reason for hiding this comment

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

I 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?

Copy link
Author

Choose a reason for hiding this comment

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

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

Copy link
Author

Choose a reason for hiding this comment

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

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.

exit 0;
fi

mkdocs serve --dev-addr=0.0.0.0:3000 --livereload
Copy link
Contributor

Choose a reason for hiding this comment

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

Does mike serve support --livereload by default?

Copy link
Author

Choose a reason for hiding this comment

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

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

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

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

@danehans danehans Jun 2, 2025

Choose a reason for hiding this comment

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

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

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

Usage:  gh release list [flags]

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

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

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

Copy link
Author

Choose a reason for hiding this comment

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

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

Regarding the errors:

could not find any release

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

Can't create a branch from itself: docs

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants