📖 Clean up getting started docs

[stmcginnis]

While reading through the Getting Started page, I noticed there were several places where things have either changed since it was originally written or incorrect names or references were copy/pasted from other docs. This updates the Getting Started page to accurately reflect what is generated when following the instructions.

There were also several typos and grammatical errors noticed while reading through the doc. Where possible, this was corrected in the Getting Started doc as well as anywhere else in the documentation where this same information was copied.

[camilamacedo86]

^ it is the testdata dir of the project where we add the examples

[stmcginnis]

Yes, but as mentioned above, that content is different than these instructions result in. The locally generated content from following the commands above are under the updated path. If we want to refer to the git repo for additional examples I think that could work. But as this part is, it can be confusing referring to a path that is not part of the local content.

[camilamacedo86]

I see; we should actually generate the sample under the docs ( with the same instructions ) as we do for the tutorials and just use the code directly from the sample.

So, that when we run make generate we will be able to keep this one update.

See:

• Here we generate the sample: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/src/cronjob-tutorial/testdata/project
• Then, you can check that in the doc we are ref, the code directly like: {{#literatego ./testdata/emptycontroller.go}} in https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/cronjob-tutorial/controller-overview.md
• You can either check the make generate target and see that we build the samples using https://github.com/kubernetes-sigs/kubebuilder/tree/master/hack/docs

Otherwise, it is hard to keep it maintained.

[varshaprasad96]

+1 to as @camilamacedo86 said. If we could directly refer the paths in the doc, that would make it easier for us to maintain it. Huge + for the idea though. We would have to probably discuss more on the how the testate would be structured to refer multi-version/multi-group scenarios for the same plugins as we have today.

[stmcginnis]

I looked in to using literatego and making this more integrated, but there were some issues with that approach. The biggest challenge is that pulls in the entire source file, when in most cases here we only want to highlight a small portion of it.

I hope I've reached a happy medium. I do now generate testdata for the getting started docs, and I try to directly pull in relevant content where possible. For the other instances, I just updated the snippet of code the docs were highlighting, but also added a link to the file in the repo so the user has a canonical reference for anything being covered. Then if they do diverge at some point, it's at least possible to follow the link to see the current full example that should match what they get locally by running the commands.

Let me know if there are any better ideas or other ways to improve that.

[camilamacedo86]

The example under test data is not built with the group cache. Is it?

[stmcginnis]

Following the instructions here in the getting started guide, this is causing a mismatch between what the resulting local files contain and what the doc later refers to. So yes, this is different than the test data, but the contents of this doc are all different.

[camilamacedo86]

I see. I am OK with the change.
Thank you for looking at this one !!!
Your help is very appreciated.

[camilamacedo86]

Hi @stmcginnis,

Really, thank you for all your collaboration 🥇
Just a few nits.

• In this PR we are addressing more than one thing. For example, the changes in the customize/v2 have no relation with getting started docs. Could you please create a PR for this only?
• Regarding the required fixes in the Getting Started doc, I think we need to properly sort it out by having the sample under docs so that it will be properly updated. See: 📖 Clean up getting started docs #3758 (comment) if you be able to do that it would be great

[varshaprasad96]

+1 to as @camilamacedo86 said. If we could directly refer the paths in the doc, that would make it easier for us to maintain it. Huge + for the idea though. We would have to probably discuss more on the how the testate would be structured to refer multi-version/multi-group scenarios for the same plugins as we have today.

[stmcginnis]

Thanks for the feedback - I will get an updated PR shortly.

One thing about the reference path though. There seems to be a disconnect in what this doc is doing, so I think we need to clarify that. As it is, the getting started guide is a tutorial/guide walking the reader through running commands and working with the generated code based on that. So I think it would be confusing to mix this "real world" walkthrough of generating the code with linking off to a static reference in the repo of a similar-but-not-quite-the-same example of what they have locally.

In other words, I think we need to keep the tutorial separate from and test data reference we could point them at.

We may want to think about changing what this guide is if we just want to refer to examples in the repo. As it is now, there are other issues with the getting started doc. The main one being that the beginning of the doc states what the user will go through and end up with at the end, but then the content of the doc only goes a short way towards those stated goals and stops. So there are definitely bigger issues that need to be decided here.

I see two main choices at this point:

1. Finish implementing the getting started guide to actually walk the user through all the declared goals, keeping with the locally generated content that the instructions generates for them; or
2. Change the getting started guide to be a description of what they can find as static content already in the repo, only explaining what local commands they could have run to get similar results on their own.

As it is now, it's a bit incomplete and disjointed.

[camilamacedo86]

Hi @stmcginnis,

There seems to be a disconnect in what this doc is doing, so I think we need to clarify that

That is all point. The tutorial describes how to create the project using the Deploy Image plugin
The examples should be exactly the code that is generated in the project.
Because of that IHMO, the right way to sort it out is by doing as we do in all other places: #3758 (comment)

All that we need to explain is scaffold when we create the API using the plugin.

[stmcginnis]

Not sure about the verification test failure. Passing locally for me, so I'm not sure what is different in my environment. Will try to investigate further.

[camilamacedo86]

Hi @stmcginnis,

GREAT WORK !!!

Not sure about the verification test failure. Passing locally for me, so I'm not sure what is different in my environment. Will try to investigate further.

It is because it is not rebased with the master branch
Just rebase your branch with master, re-run, make generate and then squash the commits, for we have just 1, and it is great to fly (we can get it merged. It will pass in all tests) !!!!

[camilamacedo86]

/lgtm

/approved

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: camilamacedo86, stmcginnis

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [camilamacedo86]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[camilamacedo86]

Hi @stmcginnis

Thank you a lot for your contribution 🥇
It is a very nice one.