📖 Clean up getting started docs #3758
Conversation
k8s-ci-robot
added
the
cncf-cla: yes
k8s-ci-robot
added
the
size/L
stmcginnis
force-pushed
the
docs/getting-started-updates
branch
from
0910fbe to
a50a971
Compare
...common/kustomize/v1/scaffolds/internal/templates/config/manager/controller_manager_config.go
Outdated
Show resolved
Hide resolved
...common/kustomize/v2/scaffolds/internal/templates/config/manager/controller_manager_config.go
Outdated
Show resolved
Hide resolved
docs/book/src/getting-started.md
Outdated
|
|
||
| From `testdata/project-v4-with-deploy-image/internal/controller/memcached_controller.go`: | ||
| From `internal/controller/memcached_controller.go`: |
There was a problem hiding this comment.
^ it is the testdata dir of the project where we add the examples
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
+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.
There was a problem hiding this comment.
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.
| @@ -33,7 +33,7 @@ kubebuilder init --domain=example.com | |||
| Next, we'll create a new API responsible for deploying and managing our Memcached solution. In this instance, we will utilize the [Deploy Image Plugin][deploy-image] to get a comprehensive code implementation for our solution. | |||
|
|
|||
| ``` | |||
| kubebuilder create api --group example.com --version v1alpha1 --kind Memcached --image=memcached:1.4.36-alpine --image-container-command="memcached,-m=64,-o,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha" --make=false | |||
| kubebuilder create api --group cache --version v1alpha1 --kind Memcached --image=memcached:1.4.36-alpine --image-container-command="memcached,-m=64,-o,modern,-v" --image-container-port="11211" --run-as-user="1001" --plugins="deploy-image/v1-alpha" --make=false | |||
There was a problem hiding this comment.
The example under test data is not built with the group cache. Is it?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
I see. I am OK with the change.
Thank you for looking at this one !!!
Your help is very appreciated.
stmcginnis
force-pushed
the
docs/getting-started-updates
branch
from
a50a971 to
9859ff7
Compare
|
Hi @stmcginnis, Really, thank you for all your collaboration 🥇
|
docs/book/src/getting-started.md
Outdated
|
|
||
| From `testdata/project-v4-with-deploy-image/internal/controller/memcached_controller.go`: | ||
| From `internal/controller/memcached_controller.go`: |
There was a problem hiding this comment.
+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.
|
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:
As it is now, it's a bit incomplete and disjointed. |
|
Hi @stmcginnis,
That is all point. The tutorial describes how to create the project using the Deploy Image plugin All that we need to explain is scaffold when we create the API using the plugin. |
stmcginnis
force-pushed
the
docs/getting-started-updates
branch
from
9859ff7 to
6f3f321
Compare
k8s-ci-robot
added
size/XXL
stmcginnis
force-pushed
the
docs/getting-started-updates
branch
from
6f3f321 to
554510b
Compare
|
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. |
|
Hi @stmcginnis, GREAT WORK !!!
It is because it is not rebased with the master branch |
stmcginnis
force-pushed
the
docs/getting-started-updates
branch
from
554510b to
627ffb8
Compare
Add generation of getting started project code This adds a step to generate the code used in the Getting Started docs page. This allows us to reference the pre-generated code relative to the docs page so we can keep things in sync between the generated code and the examples given in the docs. Fix various typos and grammar in v1alpha1 template Addresses various spelling and grammar mistakes found in the template used to generate the v1alpha1 sample projects. Addresses various typos, grammatical errors, and other refinement in the Getting Started docs page. Where possible, source files from the generated testdata project are imported directly in the docs so they stay up to date. In other areas where it wasn't practical to pull in the entire source file, this updates the code snippet shown to match the generated source and provides a link to the GitHub repo to use as a reference. Signed-off-by: Sean McGinnis <sean.mcginnis@gmail.com>
stmcginnis
force-pushed
the
docs/getting-started-updates
branch
from
627ffb8 to
f14dbc1
Compare
k8s-ci-robot
added
the
lgtm
|
[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:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
approved
|
Hi @stmcginnis Thank you a lot for your contribution 🥇 |
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.