Clean up three generate-ref-docs
Michael
windsonsea
parent
d792a64340
commit
4d6a8e57c0
|
|
@ -16,11 +16,8 @@ API or the `kube-*` components from the upstream code, see the following instruc
|
|||
- [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
- [Generating Reference Documentation for the Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
|
||||
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
|
||||
- You need to have these tools installed:
|
||||
|
||||
- [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
|
|||
For more information, see [Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/)
|
||||
and [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
||||
|
||||
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
## The big picture
|
||||
|
|
@ -51,7 +46,7 @@ from the source code in the [upstream Kubernetes](https://github.com/kubernetes/
|
|||
When you see bugs in the generated documentation, you may want to consider
|
||||
creating a patch to fix it in the upstream project.
|
||||
|
||||
## Cloning the Kubernetes repository
|
||||
## Clone the Kubernetes repository
|
||||
|
||||
If you don't already have the kubernetes/kubernetes repository, get it now:
|
||||
|
||||
|
|
@ -64,16 +59,16 @@ go get github.com/kubernetes/kubernetes
|
|||
Determine the base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
|
||||
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes`.
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
|
||||
Determine the base directory of your clone of the
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`.
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
|
||||
## Editing the Kubernetes source code
|
||||
## Edit the Kubernetes source code
|
||||
|
||||
The Kubernetes API reference documentation is automatically generated from
|
||||
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
|
|||
source code. You must change the code related to the component
|
||||
you want to fix in order to fix the generated documentation.
|
||||
|
||||
### Making changes to the upstream source code
|
||||
### Make changes to the upstream source code
|
||||
|
||||
{{< note >}}
|
||||
The following steps are an example, not a general procedure. Details
|
||||
The following steps are an example, not a general procedure. Details
|
||||
will be different in your situation.
|
||||
{{< /note >}}
|
||||
|
||||
|
|
@ -123,12 +118,12 @@ On branch master
|
|||
modified: staging/src/k8s.io/api/apps/v1/types.go
|
||||
```
|
||||
|
||||
### Committing your edited file
|
||||
### Commit your edited file
|
||||
|
||||
Run `git add` and `git commit` to commit the changes you have made so far. In the next step,
|
||||
you will do a second commit. It is important to keep your changes separated into two commits.
|
||||
|
||||
### Generating the OpenAPI spec and related files
|
||||
### Generate the OpenAPI spec and related files
|
||||
|
||||
Go to `<k8s-base>` and run these scripts:
|
||||
|
||||
|
|
@ -179,7 +174,7 @@ repository and in related repositories, such as
|
|||
[kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md).
|
||||
{{< /note >}}
|
||||
|
||||
### Cherry picking your commit into a release branch
|
||||
### Cherry pick your commit into a release branch
|
||||
|
||||
In the preceding section, you edited a file in the master branch and then ran scripts
|
||||
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
|
|||
release-{{< skew prevMinorVersion >}} branch.
|
||||
|
||||
Recall that your pull request has two commits: one for editing `types.go`
|
||||
and one for the files generated by scripts. The next step is to propose a cherry pick of your first
|
||||
and one for the files generated by scripts. The next step is to propose a cherry pick of your first
|
||||
commit into the release-{{< skew prevMinorVersion >}} branch. The idea is to cherry pick the commit
|
||||
that edited `types.go`, but not the commit that has the results of running the scripts. For instructions, see
|
||||
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md).
|
||||
|
|
@ -220,7 +215,7 @@ the same as the generated files in the master branch. The generated files in the
|
|||
contain API elements only from Kubernetes {{< skew prevMinorVersion >}}. The generated files in the master branch might contain
|
||||
API elements that are not in {{< skew prevMinorVersion >}}, but are under development for {{< skew latestVersion >}}.
|
||||
|
||||
## Generating the published reference docs
|
||||
## Generate the published reference docs
|
||||
|
||||
The preceding section showed how to edit a source file and then generate
|
||||
several files, including `api/openapi-spec/swagger.json` in the
|
||||
|
|
@ -228,16 +223,13 @@ several files, including `api/openapi-spec/swagger.json` in the
|
|||
The `swagger.json` file is the OpenAPI definition file to use for generating
|
||||
the API reference documentation.
|
||||
|
||||
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
|
||||
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
|
||||
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -10,8 +10,7 @@ This page shows how to generate the `kubectl` command reference.
|
|||
|
||||
{{< note >}}
|
||||
This topic shows how to generate reference documentation for
|
||||
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands)
|
||||
like
|
||||
[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands) like
|
||||
[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and
|
||||
[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint).
|
||||
This topic does not show how to generate the
|
||||
|
|
@ -27,9 +26,9 @@ reference page, see
|
|||
|
||||
<!-- steps -->
|
||||
|
||||
## Setting up the local repositories
|
||||
## Set up the local repositories
|
||||
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
Create a local workspace and set your `GOPATH`:
|
||||
|
||||
```shell
|
||||
mkdir -p $HOME/<workspace>
|
||||
|
|
@ -58,7 +57,7 @@ Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
|
|||
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
||||
```
|
||||
|
||||
Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`.
|
||||
Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`:
|
||||
|
||||
```shell
|
||||
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
|
|||
The kubernetes/kubernetes repository provides the `kubectl` and `kustomize` source code.
|
||||
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/k8s.io/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/k8s.io/kubernetes`.
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/<your-username>/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/<your-username>/website`.
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`.
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
|
||||
In your local k8s.io/kubernetes repository, check out the branch of interest,
|
||||
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 >}}.
|
|||
If you do not need to edit the `kubectl` source code, follow the instructions for
|
||||
[Setting build variables](#setting-build-variables).
|
||||
|
||||
## Editing the kubectl source code
|
||||
## Edit the kubectl source code
|
||||
|
||||
The kubectl command reference documentation is automatically generated from
|
||||
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.
|
|||
Monitor your pull request, and respond to reviewer comments. Continue to monitor your
|
||||
pull request until it is merged into the target branch of the kubernetes/kubernetes repository.
|
||||
|
||||
## Cherry picking your change into a release branch
|
||||
## Cherry pick your change into a release branch
|
||||
|
||||
Your change is now in the master branch, which is used for development of the next
|
||||
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
|
||||
version that has already been released, you need to propose that your change be
|
||||
cherry picked into the release branch.
|
||||
|
||||
For example, suppose the master branch is being used to develop Kubernetes
|
||||
{{< skew currentVersion >}}
|
||||
For example, suppose the master branch is being used to develop Kubernetes {{< skew currentVersion >}}
|
||||
and you want to backport your change to the release-{{< skew prevMinorVersion >}} branch. For
|
||||
instructions on how to do this, see
|
||||
[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
|
|||
need to work with someone who can set the label and milestone for you.
|
||||
{{< /note >}}
|
||||
|
||||
## Setting build variables
|
||||
## Set build variables
|
||||
|
||||
Go to `<rdocs-base>`. On you command line, set the following environment variables.
|
||||
|
||||
* Set `K8S_ROOT` to `<k8s-base>`.
|
||||
* Set `K8S_WEBROOT` to `<web-base>`.
|
||||
* Set `K8S_RELEASE` to the version of the docs you want to build.
|
||||
For example, if you want to build docs for Kubernetes {{< skew prevMinorVersion >}}, set `K8S_RELEASE` to {{< skew prevMinorVersion >}}.
|
||||
For example, if you want to build docs for Kubernetes {{< skew prevMinorVersion >}},
|
||||
set `K8S_RELEASE` to {{< skew prevMinorVersion >}}.
|
||||
|
||||
For example:
|
||||
|
||||
|
|
@ -162,13 +161,12 @@ cd <rdocs-base>
|
|||
make createversiondirs
|
||||
```
|
||||
|
||||
## Checking out a release tag in k8s.io/kubernetes
|
||||
## Check out a release tag in k8s.io/kubernetes
|
||||
|
||||
In your local `<k8s-base>` repository, checkout the branch that has
|
||||
In your local `<k8s-base>` repository, check out the branch that has
|
||||
the version of Kubernetes that you want to document. For example, if you want
|
||||
to generate docs for Kubernetes {{< skew prevMinorVersion >}}.0, check out the
|
||||
`v{{< skew prevMinorVersion >}}` tag. Make sure
|
||||
you local branch is up to date.
|
||||
`v{{< skew prevMinorVersion >}}` tag. Make sure your local branch is up to date.
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
|
|
@ -176,7 +174,7 @@ git checkout v{{< skew prevMinorVersion >}}.0
|
|||
git pull https://github.com/kubernetes/kubernetes v{{< skew prevMinorVersion >}}.0
|
||||
```
|
||||
|
||||
## Running the doc generation code
|
||||
## Run the doc generation code
|
||||
|
||||
In your local `<rdocs-base>`, run the `copycli` build target. The command runs as `root`:
|
||||
|
||||
|
|
@ -238,27 +236,21 @@ make container-serve
|
|||
|
||||
View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/).
|
||||
|
||||
## Adding and committing changes in kubernetes/website
|
||||
## Add and commit changes in kubernetes/website
|
||||
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
|
||||
## Creating a pull request
|
||||
## Create a pull request
|
||||
|
||||
Create a pull request to the `kubernetes/website` repository. Monitor your
|
||||
pull request, and respond to review comments as needed. Continue to monitor
|
||||
your pull request until it is merged.
|
||||
|
||||
A few minutes after your pull request is merged, your updated reference
|
||||
topics will be visible in the
|
||||
[published documentation](/docs/home).
|
||||
|
||||
|
||||
topics will be visible in the [published documentation](/docs/home).
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -15,23 +15,19 @@ using the [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/re
|
|||
If you find bugs in the generated documentation, you need to
|
||||
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).
|
||||
|
||||
If you need only to regenerate the reference documentation from the [OpenAPI](https://github.com/OAI/OpenAPI-Specification)
|
||||
If you need only to regenerate the reference documentation from the
|
||||
[OpenAPI](https://github.com/OAI/OpenAPI-Specification)
|
||||
spec, continue reading this page.
|
||||
|
||||
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
|
||||
{{< include "prerequisites-ref-docs.md" >}}
|
||||
|
||||
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
## Setting up the local repositories
|
||||
## Set up the local repositories
|
||||
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
Create a local workspace and set your `GOPATH`:
|
||||
|
||||
```shell
|
||||
mkdir -p $HOME/<workspace>
|
||||
|
|
@ -61,26 +57,26 @@ git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
|||
```
|
||||
|
||||
* The base directory of your clone of the
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is
|
||||
`$GOPATH/src/k8s.io/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is
|
||||
`$GOPATH/src/k8s.io/kubernetes.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
|
||||
* The base directory of your clone of the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository is
|
||||
`$GOPATH/src/github.com/<your username>/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository is
|
||||
`$GOPATH/src/github.com/<your username>/website`.
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
|
||||
* The base directory of your clone of the
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
repository is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
[kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs)
|
||||
repository is `$GOPATH/src/github.com/kubernetes-sigs/reference-docs`.
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
|
||||
## Generating the API reference docs
|
||||
## Generate the API reference docs
|
||||
|
||||
This section shows how to generate the
|
||||
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
||||
### Setting build variables
|
||||
### Set build variables
|
||||
|
||||
* Set `K8S_ROOT` to `<k8s-base>`.
|
||||
* Set `K8S_WEBROOT` to `<web-base>`.
|
||||
|
|
@ -95,9 +91,9 @@ export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
|
|||
export K8S_RELEASE=1.17.0
|
||||
```
|
||||
|
||||
### Creating versioned directory and fetching Open API spec
|
||||
### Create versioned directory and fetch Open API spec
|
||||
|
||||
The `updateapispec` build target creates the versioned build directory.
|
||||
The `updateapispec` build target creates the versioned build directory.
|
||||
After the directory is created, the Open API spec is fetched from the
|
||||
`<k8s-base>` repository. These steps ensure that the version
|
||||
of the configuration files and Kubernetes Open API spec match the release version.
|
||||
|
|
@ -110,7 +106,7 @@ cd <rdocs-base>
|
|||
make updateapispec
|
||||
```
|
||||
|
||||
### Building the API reference docs
|
||||
### Build the API reference docs
|
||||
|
||||
The `copyapi` target builds the API reference and
|
||||
copies the generated files to directories in `<web-base>`.
|
||||
|
|
@ -154,7 +150,7 @@ static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/navDat
|
|||
static/docs/reference/generated/kubernetes-api/{{< param "version" >}}/js/scroll.js
|
||||
```
|
||||
|
||||
## Updating the API reference index pages
|
||||
## Update the API reference index pages
|
||||
|
||||
When generating reference documentation for a new release, update the file,
|
||||
`<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` with the new
|
||||
|
|
@ -163,13 +159,13 @@ version number.
|
|||
* Open `<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` for editing,
|
||||
and update the API reference version number. For example:
|
||||
|
||||
```
|
||||
---
|
||||
title: v1.17
|
||||
---
|
||||
```
|
||||
---
|
||||
title: v1.17
|
||||
---
|
||||
|
||||
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
|
||||
```
|
||||
[Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
|
||||
```
|
||||
|
||||
* Open `<web-base>/content/en/docs/reference/_index.md` for editing, and add a
|
||||
new link for the latest API reference. Remove the oldest API reference version.
|
||||
|
|
@ -188,7 +184,7 @@ make container-serve
|
|||
|
||||
## Commit the changes
|
||||
|
||||
In `<web-base>` run `git add` and `git commit` to commit the change.
|
||||
In `<web-base>`, run `git add` and `git commit` to commit the change.
|
||||
|
||||
Submit your changes as a
|
||||
[pull request](/docs/contribute/new-content/open-a-pr/) to the
|
||||
|
|
@ -196,11 +192,8 @@ Submit your changes as a
|
|||
Monitor your pull request, and respond to reviewer comments as needed. Continue
|
||||
to monitor your pull request until it has been merged.
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
|
||||
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
||||
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue