Update the Multi-Version tutorial programatically when we run make generate

[camilamacedo86]

What do you want to happen?

Context:

The code that appears in the docs/tutorial came from real samples under: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src

When we do changes we need to ensure that the samples are updated with the latest changes made in the PR. Therefore, when we run make generate target which is required to push any PR it will call make generate-docs see:

kubebuilder/Makefile

Lines 66 to 69 in 7af3a37

	.PHONY: generate
	generate: generate-testdata generate-docs ## Update/generate all mock data. You should run this commands to update the mock data after your changes.
	go mod tidy
	make remove-spaces

This target calls: https://github.com/kubernetes-sigs/kubebuilder/blob/master/hack/docs/generate.sh

which will:

• a) Use kubebuilder CLI bin with the latest changes to re-generate the samples, see for example the code used to re-generate the cronjob sample used in its tutorial (https://book.kubebuilder.io/cronjob-tutorial/cronjob-tutorial): https://github.com/kubernetes-sigs/kubebuilder/blob/master/hack/docs/internal/cronjob-tutorial/generate_cronjob.go#L66-L94
• b) Replace/Add the code for the example on top, see for example that we have a file with consts for each part: https://github.com/kubernetes-sigs/kubebuilder/blob/master/hack/docs/internal/cronjob-tutorial/webhook_implementation.go and then we use the utils commands to insert/replace the content like here: https://github.com/kubernetes-sigs/kubebuilder/blob/master/hack/docs/internal/cronjob-tutorial/generate_cronjob.go#L146-L231

What do we want :

We are re-generating all samples used in the tutorials already. However, we still automate this process for the Multi-Version sample in : https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/multiversion-tutorial/testdata/project which is used in the tutorial https://book.kubebuilder.io/multiversion-tutorial/tutorial

Currently, we do it manually by:

• a) Executing the shell script: https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/multiversion-tutorial/testdata/generate_multiversion.sh
• b) Comparing the local branch with master branch and re-adding manually on top again the code implementations as the cronjob conversion : https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/multiversion-tutorial/testdata/project/api/v1/cronjob_conversion.go

Therefore, the acceptance criteria of this task is to ensure that when we run make generate / make generate-docs we should re-generate the sample in https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/multiversion-tutorial/testdata/project and have all code examples on top of it again automatically

How to do it

• 1. Ensure that the sample is updated with the latest changes, you might do this process manually once to check how it works (see above the description over how we do it manually)
• 2. See that we might not properly calling all required commands with the shell script since the conversion cronjob needs to be re-added manually. So, we must follow the tutorial https://book.kubebuilder.io/multiversion-tutorial/tutorial to ensure that we are properly generating it with the tool. Note that the Multivesion sample is the CronJob one: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/cronjob-tutorial/testdata/project generated within https://github.com/kubernetes-sigs/kubebuilder/tree/master/hack/docs/internal/cronjob-tutorial but with more one api and the conversion webhook added. The docs content which are comment in the docs are not the same either.
• 3. The code implementation should be like the other examples so you will need to create a new dir under the hack/docs/internal and ensure that the automation is implemented there.

Extra Labels

No response

[tian-ren]

Hi @camilamacedo86, I would like to work on this issue as my first issue. Is it time sensitive?

[camilamacedo86]

No, but that will b very helpful for us

[tian-ren]

Got you!

[tian-ren]

/assign