Skip to content

Navigation Menu

Sign in

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 4d6a8e5

Browse filesBrowse files
windsonseawindsonsea
committed
Clean up three generate-ref-docs
1 parent d792a64 commit 4d6a8e5
Copy full SHA for 4d6a8e5

File tree

3 files changed

+69
-92
lines changed
Filter options

3 files changed

+69
-92
lines changed

‎content/en/docs/contribute/generate-ref-docs/contribute-upstream.md

Copy file name to clipboardExpand all lines: content/en/docs/contribute/generate-ref-docs/contribute-upstream.md
+14-22
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,8 @@ API or the `kube-*` components from the upstream code, see the following instruc
1616
- [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
1717
- [Generating Reference Documentation for the Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
1818

19-
20-
2119
## {{% heading "prerequisites" %}}
2220

23-
2421
- You need to have these tools installed:
2522

2623
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
@@ -38,8 +35,6 @@ API or the `kube-*` components from the upstream code, see the following instruc
3835
For more information, see [Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/)
3936
and [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
4037

41-
42-
4338
<!-- steps -->
4439

4540
## The big picture
@@ -51,7 +46,7 @@ from the source code in the [upstream Kubernetes](https://github.com/kubernetes/
5146
When you see bugs in the generated documentation, you may want to consider
5247
creating a patch to fix it in the upstream project.
5348

54-
## Cloning the Kubernetes repository
49+
## Clone the Kubernetes repository
5550

5651
If you don't already have the kubernetes/kubernetes repository, get it now:
5752

@@ -64,16 +59,16 @@ go get github.com/kubernetes/kubernetes
6459
Determine the base directory of your clone of the
6560
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
6661
For example, if you followed the preceding step to get the repository, your
67-
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
62+
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes`.
6863
The remaining steps refer to your base directory as `<k8s-base>`.
6964

7065
Determine the base directory of your clone of the
7166
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
7267
For example, if you followed the preceding step to get the repository, your
73-
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
68+
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`.
7469
The remaining steps refer to your base directory as `<rdocs-base>`.
7570

76-
## Editing the Kubernetes source code
71+
## Edit the Kubernetes source code
7772

7873
The Kubernetes API reference documentation is automatically generated from
7974
an OpenAPI spec, which is generated from the Kubernetes source code. If you
@@ -84,10 +79,10 @@ The documentation for the `kube-*` components is also generated from the upstrea
8479
source code. You must change the code related to the component
8580
you want to fix in order to fix the generated documentation.
8681

87-
### Making changes to the upstream source code
82+
### Make changes to the upstream source code
8883

8984
{{< note >}}
90-
The following steps are an example, not a general procedure. Details
85+
The following steps are an example, not a general procedure. Details
9186
will be different in your situation.
9287
{{< /note >}}
9388

@@ -123,12 +118,12 @@ On branch master
123118
modified: staging/src/k8s.io/api/apps/v1/types.go
124119
```
125120

126-
### Committing your edited file
121+
### Commit your edited file
127122

128123
Run `git add` and `git commit` to commit the changes you have made so far. In the next step,
129124
you will do a second commit. It is important to keep your changes separated into two commits.
130125

131-
### Generating the OpenAPI spec and related files
126+
### Generate the OpenAPI spec and related files
132127

133128
Go to `<k8s-base>` and run these scripts:
134129

@@ -179,7 +174,7 @@ repository and in related repositories, such as
179174
[kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md).
180175
{{< /note >}}
181176

182-
### Cherry picking your commit into a release branch
177+
### Cherry pick your commit into a release branch
183178

184179
In the preceding section, you edited a file in the master branch and then ran scripts
185180
to generate an OpenAPI spec and related files. Then you submitted your changes in a pull request
@@ -189,7 +184,7 @@ Kubernetes version {{< skew latestVersion >}}, and you want to backport your cha
189184
release-{{< skew prevMinorVersion >}} branch.
190185

191186
Recall that your pull request has two commits: one for editing `types.go`
192-
and one for the files generated by scripts. The next step is to propose a cherry pick of your first
187+
and one for the files generated by scripts. The next step is to propose a cherry pick of your first
193188
commit into the release-{{< skew prevMinorVersion >}} branch. The idea is to cherry pick the commit
194189
that edited `types.go`, but not the commit that has the results of running the scripts. For instructions, see
195190
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
@@ -220,24 +215,21 @@ the same as the generated files in the master branch. The generated files in the
220215
contain API elements only from Kubernetes {{< skew prevMinorVersion >}}. The generated files in the master branch might contain
221216
API elements that are not in {{< skew prevMinorVersion >}}, but are under development for {{< skew latestVersion >}}.
222217

223-
## Generating the published reference docs
218+
## Generate the published reference docs
224219

225220
The preceding section showed how to edit a source file and then generate
226221
several files, including `api/openapi-spec/swagger.json` in the
227222
`kubernetes/kubernetes` repository.
228223
The `swagger.json` file is the OpenAPI definition file to use for generating
229224
the API reference documentation.
230225

231-
You are now ready to follow the [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/) guide to generate the
226+
You are now ready to follow the
227+
[Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
228+
guide to generate the
232229
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
233230

234-
235-
236231
## {{% heading "whatsnext" %}}
237232

238-
239233
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
240234
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
241235
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
242-
243-

‎content/en/docs/contribute/generate-ref-docs/kubectl.md

Copy file name to clipboardExpand all lines: content/en/docs/contribute/generate-ref-docs/kubectl.md
+29-37
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,7 @@ This page shows how to generate the `kubectl` command reference.
1010

1111
{{< note >}}
1212
This topic shows how to generate reference documentation for
13-
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands)
14-
like
13+
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands) like
1514
[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and
1615
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint).
1716
This topic does not show how to generate the
@@ -27,9 +26,9 @@ reference page, see
2726

2827
<!-- steps -->
2928

30-
## Setting up the local repositories
29+
## Set up the local repositories
3130

32-
Create a local workspace and set your `GOPATH`.
31+
Create a local workspace and set your `GOPATH`:
3332

3433
```shell
3534
mkdir -p $HOME/<workspace>
@@ -58,7 +57,7 @@ Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
5857
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
5958
```
6059

61-
Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`.
60+
Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`:
6261

6362
```shell
6463
rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
@@ -67,22 +66,22 @@ rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
6766
The kubernetes/kubernetes repository provides the `kubectl` and `kustomize` source code.
6867

6968
* Determine the base directory of your clone of the
70-
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
71-
For example, if you followed the preceding step to get the repository, your
72-
base directory is `$GOPATH/src/k8s.io/kubernetes.`
73-
The remaining steps refer to your base directory as `<k8s-base>`.
69+
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
70+
For example, if you followed the preceding step to get the repository, your
71+
base directory is `$GOPATH/src/k8s.io/kubernetes`.
72+
The remaining steps refer to your base directory as `<k8s-base>`.
7473

7574
* Determine the base directory of your clone of the
76-
[kubernetes/website](https://github.com/kubernetes/website) repository.
77-
For example, if you followed the preceding step to get the repository, your
78-
base directory is `$GOPATH/src/github.com/<your-username>/website.`
79-
The remaining steps refer to your base directory as `<web-base>`.
75+
[kubernetes/website](https://github.com/kubernetes/website) repository.
76+
For example, if you followed the preceding step to get the repository, your
77+
base directory is `$GOPATH/src/github.com/<your-username>/website`.
78+
The remaining steps refer to your base directory as `<web-base>`.
8079

8180
* Determine the base directory of your clone of the
82-
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
83-
For example, if you followed the preceding step to get the repository, your
84-
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
85-
The remaining steps refer to your base directory as `<rdocs-base>`.
81+
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
82+
For example, if you followed the preceding step to get the repository, your
83+
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`.
84+
The remaining steps refer to your base directory as `<rdocs-base>`.
8685

8786
In your local k8s.io/kubernetes repository, check out the branch of interest,
8887
and make sure it is up to date. For example, if you want to generate docs for
@@ -97,7 +96,7 @@ git pull https://github.com/kubernetes/kubernetes {{< skew prevMinorVersion >}}.
9796
If you do not need to edit the `kubectl` source code, follow the instructions for
9897
[Setting build variables](#setting-build-variables).
9998

100-
## Editing the kubectl source code
99+
## Edit the kubectl source code
101100

102101
The kubectl command reference documentation is automatically generated from
103102
the kubectl source code. If you want to change the reference documentation, the first step
@@ -111,15 +110,14 @@ is an example of a pull request that fixes a typo in the kubectl source code.
111110
Monitor your pull request, and respond to reviewer comments. Continue to monitor your
112111
pull request until it is merged into the target branch of the kubernetes/kubernetes repository.
113112

114-
## Cherry picking your change into a release branch
113+
## Cherry pick your change into a release branch
115114

116115
Your change is now in the master branch, which is used for development of the next
117116
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
118117
version that has already been released, you need to propose that your change be
119118
cherry picked into the release branch.
120119

121-
For example, suppose the master branch is being used to develop Kubernetes
122-
{{< skew currentVersion >}}
120+
For example, suppose the master branch is being used to develop Kubernetes {{< skew currentVersion >}}
123121
and you want to backport your change to the release-{{< skew prevMinorVersion >}} branch. For
124122
instructions on how to do this, see
125123
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
@@ -132,14 +130,15 @@ milestone in your pull request. If you don't have those permissions, you will
132130
need to work with someone who can set the label and milestone for you.
133131
{{< /note >}}
134132

135-
## Setting build variables
133+
## Set build variables
136134

137135
Go to `<rdocs-base>`. On you command line, set the following environment variables.
138136

139137
* Set `K8S_ROOT` to `<k8s-base>`.
140138
* Set `K8S_WEBROOT` to `<web-base>`.
141139
* Set `K8S_RELEASE` to the version of the docs you want to build.
142-
For example, if you want to build docs for Kubernetes {{< skew prevMinorVersion >}}, set `K8S_RELEASE` to {{< skew prevMinorVersion >}}.
140+
For example, if you want to build docs for Kubernetes {{< skew prevMinorVersion >}},
141+
set `K8S_RELEASE` to {{< skew prevMinorVersion >}}.
143142

144143
For example:
145144

@@ -162,21 +161,20 @@ cd <rdocs-base>
162161
make createversiondirs
163162
```
164163

165-
## Checking out a release tag in k8s.io/kubernetes
164+
## Check out a release tag in k8s.io/kubernetes
166165

167-
In your local `<k8s-base>` repository, checkout the branch that has
166+
In your local `<k8s-base>` repository, check out the branch that has
168167
the version of Kubernetes that you want to document. For example, if you want
169168
to generate docs for Kubernetes {{< skew prevMinorVersion >}}.0, check out the
170-
`v{{< skew prevMinorVersion >}}` tag. Make sure
171-
you local branch is up to date.
169+
`v{{< skew prevMinorVersion >}}` tag. Make sure your local branch is up to date.
172170

173171
```shell
174172
cd <k8s-base>
175173
git checkout v{{< skew prevMinorVersion >}}.0
176174
git pull https://github.com/kubernetes/kubernetes v{{< skew prevMinorVersion >}}.0
177175
```
178176

179-
## Running the doc generation code
177+
## Run the doc generation code
180178

181179
In your local `<rdocs-base>`, run the `copycli` build target. The command runs as `root`:
182180

@@ -238,27 +236,21 @@ make container-serve
238236

239237
View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/).
240238

241-
## Adding and committing changes in kubernetes/website
239+
## Add and commit changes in kubernetes/website
242240

243241
Run `git add` and `git commit` to commit the files.
244242

245-
## Creating a pull request
243+
## Create a pull request
246244

247245
Create a pull request to the `kubernetes/website` repository. Monitor your
248246
pull request, and respond to review comments as needed. Continue to monitor
249247
your pull request until it is merged.
250248

251249
A few minutes after your pull request is merged, your updated reference
252-
topics will be visible in the
253-
[published documentation](/docs/home).
254-
255-
250+
topics will be visible in the [published documentation](/docs/home).
256251

257252
## {{% heading "whatsnext" %}}
258253

259-
260254
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
261255
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
262256
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
263-
264-

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.