update kubectl ref contrib guide (#15199)
* [WIP] update kubectl ref contrib guide * updates to kubectl cmd ref contrib
This commit is contained in:
Karen Bradshaw
Kubernetes Prow Robot
parent
71e027895e
commit
0c4353e86c
|
|
@ -48,64 +48,80 @@ information, see
|
|||
|
||||
{{% capture steps %}}
|
||||
|
||||
## Getting three repositories
|
||||
## Setting up the local repositories
|
||||
|
||||
If you don't already have the kubernetes/kubernetes repository, get it now:
|
||||
Create a local workspace and set your `GOPATH`.
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes/kubernetes
|
||||
mkdir -p $HOME/<workspace>
|
||||
|
||||
export GOPATH=$HOME/<workspace>
|
||||
```
|
||||
|
||||
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.`
|
||||
The remaining steps refer to your base directory as `<k8s-base>`.
|
||||
Get a local clone of the following repositories:
|
||||
|
||||
```shell
|
||||
go get -u github.com/spf13/pflag
|
||||
go get -u github.com/spf13/cobra
|
||||
go get -u gopkg.in/yaml.v2
|
||||
go get -u kubernetes-incubator/reference-docs
|
||||
```
|
||||
|
||||
If you don't already have the kubernetes/website repository, get it now:
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes/website
|
||||
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
|
||||
```
|
||||
|
||||
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/kubernetes/website.`
|
||||
The remaining steps refer to your base directory as `<web-base>`.
|
||||
|
||||
If you don't already have the kubernetes-incubator/reference-docs repository, get it now:
|
||||
Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
|
||||
|
||||
```shell
|
||||
mkdir $GOPATH/src
|
||||
cd $GOPATH/src
|
||||
go get github.com/kubernetes-incubator/reference-docs
|
||||
git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
|
||||
```
|
||||
|
||||
Determine the base directory of your clone of the
|
||||
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
|
||||
```
|
||||
|
||||
The kubernetes/kubernetes repository provides access to 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>`.
|
||||
|
||||
* 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>`.
|
||||
|
||||
* Determine the base directory of your clone of the
|
||||
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) repository.
|
||||
For example, if you followed the preceding step to get the repository, your
|
||||
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
|
||||
The remaining steps refer to your base directory as `<rdocs-base>`.
|
||||
|
||||
In your local kubernetes/kubernetes repository, check out the branch of interest,
|
||||
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
|
||||
Kubernetes 1.9, you could use these commands:
|
||||
Kubernetes 1.15, you could use these commands:
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout release-1.9
|
||||
git pull https://github.com/kubernetes/kubernetes release-1.9
|
||||
git checkout release-1.15
|
||||
git pull https://github.com/kubernetes/kubernetes release-1.15
|
||||
```
|
||||
|
||||
If you do not need to edit the kubectl source code, follow the instructions to [Edit the Makefile](#editing-makefile).
|
||||
|
||||
## Editing the kubectl source code
|
||||
|
||||
The reference documentation for the kubectl commands is automatically generated from
|
||||
kubectl source code. If you want to change the reference documentation, the first step
|
||||
The kubectl command reference documentation is automatically generated from
|
||||
the kubectl source code. If you want to change the reference documentation, the first step
|
||||
is to change one or more comments in the kubectl source code. Make the change in your
|
||||
local kubernetes/kubernetes repository, and then submit a pull request to the master branch of
|
||||
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
|
||||
|
|
@ -124,7 +140,7 @@ 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 1.10,
|
||||
and you want to backport your change to the release-1.9 branch. For instructions
|
||||
and you want to backport your change to the release-1.15 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).
|
||||
|
||||
|
|
@ -138,104 +154,115 @@ need to work with someone who can set the label and milestone for you.
|
|||
|
||||
## Editing Makefile
|
||||
|
||||
Go to `<rdocs-base>`, and open `Makefile` for editing:
|
||||
Go to `<rdocs-base>`, and open the `Makefile` for editing:
|
||||
|
||||
Set `K8SROOT` to the base directory of your local kubernetes/kubernetes
|
||||
repository. Set `WEBROOT` to the base directory of your local kubernetes/website repository.
|
||||
Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
|
||||
if you want to build docs for Kubernetes 1.9, set `MINOR_VERSION` to 9. Save and close `Makefile`.
|
||||
* Set `K8SROOT` to `<k8s-base>`.
|
||||
* Set `WEBROOT` to `<web-base>`.
|
||||
* Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
|
||||
if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
|
||||
|
||||
## Building the brodocs image
|
||||
For example, update the following variables:
|
||||
|
||||
The doc generation code requires the `pwittrock/brodocs` Docker image.
|
||||
|
||||
This command creates the `pwittrock/brodocs` Docker image. It also tries to push the image to
|
||||
DockerHub, but it's OK if that step fails. As long as you have the image locally, the code generation
|
||||
can succeed.
|
||||
|
||||
|
||||
```shell
|
||||
make brodocs
|
||||
```
|
||||
|
||||
Verify that you have the brodocs image:
|
||||
|
||||
```shell
|
||||
docker images
|
||||
```
|
||||
|
||||
The output shows `pwittrock/brodocs` as one of the available images:
|
||||
|
||||
```shell
|
||||
REPOSITORY TAG IMAGE ID CREATED SIZE
|
||||
pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB
|
||||
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
|
||||
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
|
||||
MINOR_VERSION=15
|
||||
```
|
||||
|
||||
## Creating a version directory
|
||||
|
||||
In the `gen-kubectldocs/generators` directory, if you do not already
|
||||
have a directory named `v1_MINOR_VERSION`, create one now by copying the directory
|
||||
The version directory is a staging area for the kubectl command reference build.
|
||||
The YAML files in this directory are used to create the structure and navigation
|
||||
of the kubectl command reference.
|
||||
|
||||
In the `<rdocs-base>/gen-kubectldocs/generators` directory, if you do not already
|
||||
have a directory named `v1_<MINOR_VERSION>`, create one now by copying the directory
|
||||
for the previous version. For example, suppose you want to generate docs for
|
||||
Kubernetes 1.9, but you don't already have a `v1_9` directory. Then you could
|
||||
create and populate a `v1_9` directory by running these commands:
|
||||
Kubernetes 1.15, but you don't already have a `v1_15` directory. Then you could
|
||||
create and populate a `v1_15` directory by running these commands:
|
||||
|
||||
```shell
|
||||
mkdir gen-kubectldocs/generators/v1_9
|
||||
cp -r gen-kubectldocs/generators/v1_8/* gen-kubectldocs/generators/v1_9
|
||||
mkdir gen-kubectldocs/generators/v1_15
|
||||
cp -r gen-kubectldocs/generators/v1_14/* gen-kubectldocs/generators/v1_15
|
||||
```
|
||||
|
||||
## Checking out a branch in kubernetes/kubernetes
|
||||
## Checking out a branch in k8s.io/kubernetes
|
||||
|
||||
In you local kubernetes/kubernetes repository, checkout the branch that has
|
||||
In your local <k8s-base> repository, checkout the branch that has
|
||||
the version of Kubernetes that you want to document. For example, if you want
|
||||
to generate docs for Kubernetes 1.9, checkout the release-1.9 branch. Make sure
|
||||
to generate docs for Kubernetes 1.15, checkout the release-1.15 branch. Make sure
|
||||
you local branch is up to date.
|
||||
|
||||
```shell
|
||||
cd <k8s-base>
|
||||
git checkout release-1.15
|
||||
git pull https://github.com/kubernetes/kubernetes release-1.15
|
||||
```
|
||||
|
||||
## Running the doc generation code
|
||||
|
||||
In you local kubernetes-incubator/reference-docs repository, build and run the
|
||||
doc generation code. You might need to run the command as root:
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make cli
|
||||
```
|
||||
|
||||
## Locate the generated files
|
||||
|
||||
These two files are the primary output of a successful build. Verify that they exist:
|
||||
|
||||
* `<rdocs-base>/gen-kubectldocs/generators/build/index.html`
|
||||
* `<rdocs-base>/gen-kubectldocs/generators/build/navData.js`
|
||||
|
||||
## Copying files to the kubernetes/website repository
|
||||
|
||||
Copy the generated files from your local kubernetes-incubator/reference-docs
|
||||
repository to your local kubernetes/website repository.
|
||||
In your local kubernetes-incubator/reference-docs repository, build and run the
|
||||
kubectl command reference generation code. You might need to run the command as root:
|
||||
|
||||
```shell
|
||||
cd <rdocs-base>
|
||||
make copycli
|
||||
```
|
||||
|
||||
## Adding and committing changes in kubernetes/website
|
||||
The `copycli` command will clean the staging directories, generate the kubectl command files,
|
||||
and copy the collated kubectl reference HTML page and assets to `<web-base>`.
|
||||
|
||||
List the files that were generated and copied to the `kubernetes/website`
|
||||
repository:
|
||||
## Locate the generated files
|
||||
|
||||
Verify that these two files have been generated:
|
||||
|
||||
```shell
|
||||
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
|
||||
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
|
||||
```
|
||||
|
||||
## Locate the copied files
|
||||
|
||||
Verify that all generated files have been copied to your `<web-base>`:
|
||||
|
||||
```shell
|
||||
cd <web-base>
|
||||
git status
|
||||
```
|
||||
|
||||
The output shows the new and modified files. For example, the output
|
||||
might look like this:
|
||||
The output should include the modified files:
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubectl/kubectl-commands.html
|
||||
static/docs/reference/generated/kubectl/navData.js
|
||||
```
|
||||
|
||||
Additionally, the output might show the modified files:
|
||||
|
||||
```
|
||||
static/docs/reference/generated/kubectl/scroll.js
|
||||
static/docs/reference/generated/kubectl/stylesheet.css
|
||||
static/docs/reference/generated/kubectl/tabvisibility.js
|
||||
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
|
||||
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
|
||||
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
|
||||
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css
|
||||
```
|
||||
|
||||
## Locally test the documentation
|
||||
|
||||
Build the Kubernetes documentation in your local `<web-base>`.
|
||||
|
||||
```shell
|
||||
modified: docs/reference/generated/kubectl/kubectl-commands.html
|
||||
modified: docs/reference/generated/kubectl/navData.js
|
||||
cd <web-base>
|
||||
make docker-serve
|
||||
```
|
||||
|
||||
View the [local preview](https://localhost:1313/docs/reference/generated/kubectl/kubectl-commands/).
|
||||
|
||||
## Adding and committing changes in kubernetes/website
|
||||
|
||||
Run `git add` and `git commit` to commit the files.
|
||||
|
||||
## Creating a pull request
|
||||
|
|
@ -257,7 +284,4 @@ topics will be visible in the
|
|||
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
|
||||
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
|
||||
{{% /capture %}}
|
||||
Loading…
Reference in New Issue