Kubebuilder: Docs cleanup

[Adirio]

The book needs to be cleaned up.

• [ ] The files are not completely up-to-date and the tutorial should be followed step by step and checking the differences in the code as tracked in #1251
• [x] Is the folder /docs/book/src/migration/testdata being used for anything? It should be removed if it isn't. Why should we have a testdata folder that is the one used by the golden script inside one of the book chapters?
• [ ] Several files related to the old documentation like migration from v0, gifs, or some files that look like the utils used for previous versions of the documentation before moving to the new book format are still found in this directory

/kind cleanup

[DirectXMan12]

/good-first-issue

[k8s-ci-robot]

@DirectXMan12:
This request has been marked as suitable for new contributors.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-good-first-issue command.

In response to this:

/good-first-issue

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/test-infra repository.

[vnzongzna]

Hi, I would like to work on it.
/assign

[Adirio]

@vaibhavk the first point should be pretty straightforward. Just follow the tutorial in a new project and doccument the differences in the file.

Second point requires to verify that the testdata directory is not used for anything, and remove it.

Third would require deep undestanding of the whole book creation process.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[Adirio]

/lifecycle frozen

[camilamacedo86]

Hi @Adirio,

Following a few comments inline.

The files are not completely up-to-date and the tutorial should be followed step by step and checking the differences in the code as tracked in #1251

It shows a duplicate of #1251 so I think that can be removed from the scope of this issue. I mean the repo has another issue already to address the same. Also, the PR: https://github.com/kubernetes-sigs/kubebuilder/pull/1492/files probably address it.

Is the folder /docs/book/src/migration/testdata being used for anything? It should be removed if it isn't. Why should we have a testdata folder that is the one used by the golden script inside one of the book chapters?

The /docs/book/src/migration/testdata is used just in the migration guide to help users move forward from V1 to V2. Since V1 was deprecated to long and has no longer supported I think we could keep the migration guide to still having the info but remove the examples/testdata.

Several files related to the old documentation like migration from v0, gifs, or some files that look like the utils used for previous versions of the documentation before moving to the new book format are still found in this directory

I think the above would solve this one as well. WDYT?

[camilamacedo86]

/assign @camilamacedo86

[Adirio]

I listed them to remember we need to do it but I don't have enough knowledge of the inner workins of how the documentation is generated to really know if those files are being used somewhere or they aren't.

You are saying that the testdata folder is being used for something so I would say we should keep it as long as we keep the migration guide (as you can see, that point was a question because I didn't know if it was being used or not). So, IMHO, we should remove that point from the list here and not remove the testdata folder until we remove the migration guide (if we ever do that).

[camilamacedo86]

HI @Adirio,

Sorry, may I could not clarify properly my thoughts. Following some comments

Regards 1th Item

• The first item of the list, is duplicated of #1251. So, IMO should not be here

Regards 2th Item

• The /docs/book/src/migration/testdata shows quite safe be removed at this point. See: https://github.com/kubernetes-sigs/kubebuilder/pull/1499

PS.: IMO we should not migrate to the migration guide. We can create new ones when/if is required. It is a doc that should exist with its steps as history. We just do not need to keep /docs/book/src/migration/testdata because it is not really adding value to the info, also v1 is deprecated/not supported and currently removed and no longer it would be updated. I mean the /docs/book/src/migration/testdata is not required for users to migrate their projects and follow up the steps at all.

Regards 3th Item

• I understand that the 3th item of this list also could be solved with the above solution.

[Adirio]

Yeah, I understood you correctly. What I mean is, if we have the migration guide (v1->v2) we keep the corresponding testdata folder, if we remove that guide we remove the folder.

And yes, the first point is tracked in another Issue, this is just a list of things that were needed. Things can be removed or marked as done once they get resolved.

[camilamacedo86]

added all detailed reasons why in POV is quite safe to delete the example of a V1 project that is just used in the migration guide from V1 to V2 in the PR: https://github.com/kubernetes-sigs/kubebuilder/pull/1499#issuecomment-628038450