diff --git a/content/en/docs/contribute/generate-ref-docs/kubectl.md b/content/en/docs/contribute/generate-ref-docs/kubectl.md index 04bbb2dc21..2194e99308 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubectl.md +++ b/content/en/docs/contribute/generate-ref-docs/kubectl.md @@ -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/ + +export GOPATH=$HOME/ ``` -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 ``. +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//website $GOPATH/src/github.com//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 ``. - -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 ``. + +* 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//website.` +The remaining steps refer to your base directory as ``. + +* 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 ``. -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 -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 ``, and open `Makefile` for editing: +Go to ``, 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 ``. +* Set `WEBROOT` to ``. +* 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//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 `/gen-kubectldocs/generators` directory, if you do not already +have a directory named `v1_`, 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 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 +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 -make cli -``` - -## Locate the generated files - -These two files are the primary output of a successful build. Verify that they exist: - -* `/gen-kubectldocs/generators/build/index.html` -* `/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 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 ``. -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 "/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html" +[ -e "/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 ``: + +```shell cd 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 ``. ```shell -modified: docs/reference/generated/kubectl/kubectl-commands.html -modified: docs/reference/generated/kubectl/navData.js +cd +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 %}} \ No newline at end of file