Docs versioning

[artberger]

Summary:

• As a user, I want to quickly review the docs for the particular version that I have.
• As a contributor, I want to be able to document the way that a feature works without overwriting the steps that were accurate for a past release.

Initial approach:

• Try out the MkDocs Material theme's versioning capability
• Figure out how to integrate versioned docs into the doc build process

More resources:

• Issue where doc versioning first came up: Quickstart Started Guide Does Not Work #407
• Feb 27, 2025 meeting minutes where doc versioning was discussed

[danehans]

@artberger I have assigned this issue to you. It would be great if this issue can be resolved in time for the v0.2.0 release. Track the milestones for upcoming details on the release date. cc: @ahg-g in case this issue should be added to #362.

[liu-cong]

@artberger

This issue is currently in the v0.4 release tracker and v0.4 release is planned for Mid-June. Can you provide an estimate if this can be finished in the week of June 9?

Based on the estimate, we can decide whether to include this or postpone it to the v0.5 release. Thanks!

[artberger]

@liu-cong thanks for following up. While it is possible that it might be finished next week (working PR), I am waiting on help from k8s GitHub/Netlify admins (ref Slack thread), so I am not sure on their availability. If we could postpone to the v0.5 release or a fast-follow post v0.4, that might be more realistic.

[liu-cong]

Thanks for the update! We can check back next week again and postpone if not done.

[danehans]

Bumped to v0.5 since @artberger is blocked due to #422 (comment).

@artberger I played around with docs versioning here earlier this week. This fork uses a GH action to trigger the versioned docs build and does not require a separate branch. This PR failed CI, but it's because GitHub Actions are not supported for this repository. I believe this process needs to be followed to have CI trigger the docs versioning (latest version for main branch and vX.X for tagged releases. You can also ref kubernetes/test-infra#34974 which adds an e2e CI job. LMKWYT.

@robscott thoughts on ^?

[artberger]

@danehans I updated my fork and Netlify preview site to use a GitHub workflow approach, based on your PR. For now, it just does the version dropdown and v0.3.1 manual test quote that changes per version, not any of the content changes per version.

Perhaps we can review to confirm that this approach would be better than #869 and the next steps?