SIG Docs Tech Leads to learn/document reference docs generation process for a Kubernetes release about website HOT 4 OPEN

At present, Qiming adapts the generators for the new release and proposes PRs directly to the website repo. Generating the references during adaptation takes place in parallel, which is a "simple" way to describe the current process.

I think @feloy has also worked on reference docs changes that relate to https://kubernetes.io/docs/reference/kubernetes-api/

(As far as I know) we don't have a documented process for updating https://kubernetes.io/docs/reference/kubernetes-api/ once a new release is imminent.

from website.

I have a process improvement suggestion.

At code freeze, could we update the dev branch for the upcoming release with interim docs, and then do a post-release PR to cover any API or tool updates that landed during code freeze?
We could potentially add a Prow command or similar tooling to automate part of this. @dims helped make some similar automation for k/k updates.

from website.

At present, Qiming adapts the generators for the new release and proposes PRs directly to the website repo. Generating the references during adaptation takes place in parallel, which is a "simple" way to describe the current process.

I think @feloy has also worked on reference docs changes that relate to https://kubernetes.io/docs/reference/kubernetes-api/

Right, I've maintained this documentation for releases v1.22 to v1.28. Due to other engagement, I have not been able to update it for the last two releases.

(As far as I know) we don't have a documented process for updating https://kubernetes.io/docs/reference/kubernetes-api/ once a new release is imminent.

The process is concisely described at: https://github.com/kubernetes/website/blob/main/README.md#building-the-api-reference-pages

The point 3/ of the documentation is probably the one needing some knowledge of how the generator works / some experience. I proposed a few releases ago to have some live call with docs maintainers to make some "pair programming" together, to be able to share this knowledge. My proposition is still valid.

For these changes, you don't particularly need the tag to exist. You just need to be confident that the swagger file, on which the generation relies, won't be changed afterwards.

from website.

The API reference generator takes the swagger file as its input. There is no dependency upon other kubernetes repos. Once we are confident that swagger file won't change, the reference page can be generated prior to a release.

However, all other reference generators depend on the existence of git tags which are only available when a new release is cut. Generating interim docs may complicate the whole process for no good I'm aware of.

from website.