whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update kubectl ref contrib guide (#15199)

Browse Source 
* [WIP] update kubectl ref contrib guide

* updates to kubectl cmd ref contrib
This commit is contained in:
Karen Bradshaw
2019-07-06 07:54:35 -04:00
committed by Kubernetes Prow Robot
parent 71e027895e
commit 0c4353e86c
1 changed files with 121 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/generate-ref-docs/kubectl.md
+121 -97
View File
@@ -48,64 +48,80 @@ information, see
{{% capture steps %}} {{% 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 ```shell
mkdir $GOPATH/src mkdir -p $HOME/<workspace>
cd $GOPATH/src
go get github.com/kubernetes/kubernetes export GOPATH=$HOME/<workspace>
``` ```
Determine the base directory of your clone of the Get a local clone of the following repositories:
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
For example, if you followed the preceding step to get the repository, your ```shell
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.` go get -u github.com/spf13/pflag
The remaining steps refer to your base directory as `<k8s-base>`. 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: If you don't already have the kubernetes/website repository, get it now:
```shell ```shell
mkdir $GOPATH/src git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
cd $GOPATH/src
go get github.com/kubernetes/website
``` ```
Determine the base directory of your clone of the Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
[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:
```shell ```shell
mkdir $GOPATH/src git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs
``` ```
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. [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 For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.` base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`. 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 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 ```shell
cd <k8s-base> cd <k8s-base>
git checkout release-1.9 git checkout release-1.15
git pull https://github.com/kubernetes/kubernetes release-1.9 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 ## Editing the kubectl source code
The reference documentation for the kubectl commands is automatically generated from The kubectl command reference documentation is automatically generated from
kubectl source code. If you want to change the reference documentation, the first step 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 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 local kubernetes/kubernetes repository, and then submit a pull request to the master branch of
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). [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. cherry picked into the release branch.
For example, suppose the master branch is being used to develop Kubernetes 1.10, 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 on how to do this, see
[Propose a Cherry Pick](https://git.k8s.io/community/contributors/devel/sig-release/cherry-picks.md). [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 ## 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 * Set `K8SROOT` to `<k8s-base>`.
repository. Set `WEBROOT` to the base directory of your local kubernetes/website repository. * Set `WEBROOT` to `<web-base>`.
Set `MINOR_VERSION` to the minor version of the docs you want to build. For example, * 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`. 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
``` ```
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
Verify that you have the brodocs image: K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15
```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
``` ```
## Creating a version directory ## Creating a version directory
In the `gen-kubectldocs/generators` directory, if you do not already The version directory is a staging area for the kubectl command reference build.
have a directory named `v1_MINOR_VERSION`, create one now by copying the directory 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 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 Kubernetes 1.15, but you don't already have a `v1_15` directory. Then you could
create and populate a `v1_9` directory by running these commands: create and populate a `v1_15` directory by running these commands:
```shell ```shell
mkdir gen-kubectldocs/generators/v1_9 mkdir gen-kubectldocs/generators/v1_15
cp -r gen-kubectldocs/generators/v1_8/* gen-kubectldocs/generators/v1_9 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 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. 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 ## Running the doc generation code
In you local kubernetes-incubator/reference-docs repository, build and run the In your local kubernetes-incubator/reference-docs repository, build and run the
doc generation code. You might need to run the command as root: kubectl command reference 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.
```shell ```shell
cd <rdocs-base> cd <rdocs-base>
make copycli 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` ## Locate the generated files
repository:
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> cd <web-base>
git status git status
``` ```
The output shows the new and modified files. For example, the output The output should include the modified files:
might look like this:
```
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 ```shell
modified: docs/reference/generated/kubectl/kubectl-commands.html cd <web-base>
modified: docs/reference/generated/kubectl/navData.js 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. Run `git add` and `git commit` to commit the files.
## Creating a pull request ## 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 API](/docs/home/contribute/generated-reference/kubernetes-api/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/) * [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
{{% /capture %}} {{% /capture %}}