From a2135415cc0e8aff4c0914f271593835299e2015 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Sat, 29 Jun 2019 12:21:01 -0400 Subject: [PATCH 1/2] [WIP] update kubectl ref contrib guide --- .../contribute/generate-ref-docs/kubectl.md | 158 ++++++++---------- 1 file changed, 74 insertions(+), 84 deletions(-) diff --git a/content/en/docs/contribute/generate-ref-docs/kubectl.md b/content/en/docs/contribute/generate-ref-docs/kubectl.md index 04bbb2dc210be..f0e33e28b33a6 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubectl.md +++ b/content/en/docs/contribute/generate-ref-docs/kubectl.md @@ -48,64 +48,69 @@ 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 workspace to clone the local repositories and set your `GOPATH`. ```shell -mkdir $GOPATH/src -cd $GOPATH/src -go get github.com/kubernetes/kubernetes +mkdir -p $HOME/ # make sure the directory exists + +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 ``. +To build the kubectl command reference guide, you need to have a local clone +of the following repositories: + +``` +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 +go get -u k8s.io/kubernetes +``` + +Manually remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor`. + +The k8s.io/kubernetes repository provides access to the kubectl and kustomize source code. 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 +* Determine the base directory of your clone of the +[k8s.io/kubernetes](https://github.com/k8s.io/kubernetes) repository. +For example, if you followed the preceding step to get the repository, your +base directory is `$GOPATH/src/github.com/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/kubernetes/website.` +base directory is `$GOPATH/src/github.com//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: - -```shell -mkdir $GOPATH/src -cd $GOPATH/src -go get github.com/kubernetes-incubator/reference-docs -``` - -Determine the base directory of your clone of the +* 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 ``` ## 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). @@ -138,69 +143,55 @@ need to work with someone who can set the label and milestone for you. ## Editing Makefile -Go to ``, and open `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`. - -## Building the brodocs image - -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: +Go to ``, and open the `Makefile` for editing: -```shell -REPOSITORY TAG IMAGE ID CREATED SIZE -pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB -``` +* 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`. ## 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 +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 +The version directory is a staging area for the kubectl command reference build. +The YAML files are used to create the structure and navigation for the new reference. + +## 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/k8s.io/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: +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 cli +make copycli ``` +The `copycli` command will clean the staging directories, generate the kubectl command files, +and copy the collated html page and assets to ``. + ## Locate the generated files These two files are the primary output of a successful build. Verify that they exist: @@ -208,20 +199,22 @@ These two files are the primary output of a successful build. Verify that they e * `/gen-kubectldocs/generators/build/index.html` * `/gen-kubectldocs/generators/build/navData.js` -## Copying files to the kubernetes/website repository +## Locally test the documentation -Copy the generated files from your local kubernetes-incubator/reference-docs -repository to your local kubernetes/website repository. +Build the Kubernetes documentation in your local ``. ```shell -cd -make copycli +cd +make docker-serve ``` +View the [local preview](/docs/reference/generated/kubectl/kubectl-cmds/) of the reference from: + +`https://localhost:1313` + ## Adding and committing changes in kubernetes/website -List the files that were generated and copied to the `kubernetes/website` -repository: +List the files that were generated and copied to the ``: ``` cd @@ -257,7 +250,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 From a648dc16f2b253462f4f104a1e9e93bab7b50bcb Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Mon, 1 Jul 2019 14:21:10 -0400 Subject: [PATCH 2/2] updates to kubectl cmd ref contrib --- .../contribute/generate-ref-docs/kubectl.md | 104 ++++++++++++------ 1 file changed, 69 insertions(+), 35 deletions(-) diff --git a/content/en/docs/contribute/generate-ref-docs/kubectl.md b/content/en/docs/contribute/generate-ref-docs/kubectl.md index f0e33e28b33a6..2194e9930885e 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubectl.md +++ b/content/en/docs/contribute/generate-ref-docs/kubectl.md @@ -50,39 +50,48 @@ information, see ## Setting up the local repositories -Create a workspace to clone the local repositories and set your `GOPATH`. +Create a local workspace and set your `GOPATH`. ```shell -mkdir -p $HOME/ # make sure the directory exists +mkdir -p $HOME/ export GOPATH=$HOME/ ``` -To build the kubectl command reference guide, you need to have a local clone -of the following repositories: +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 -go get -u k8s.io/kubernetes ``` -Manually remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor`. - -The k8s.io/kubernetes repository provides access to the kubectl and kustomize source code. - If you don't already have the kubernetes/website repository, get it now: ```shell git clone https://github.com//website $GOPATH/src/github.com//website ``` +Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes: + +```shell +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`. + +```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 -[k8s.io/kubernetes](https://github.com/k8s.io/kubernetes) repository. +[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/k8s.io/kubernetes.` +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 @@ -107,6 +116,8 @@ 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 kubectl command reference documentation is automatically generated from @@ -129,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). @@ -150,8 +161,20 @@ Go to ``, and open the `Makefile` for editing: * 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`. +For example, update the following variables: + +``` +WEBROOT=$(GOPATH)/src/github.com//website +K8SROOT=$(GOPATH)/src/k8s.io/kubernetes +MINOR_VERSION=15 +``` + ## Creating a version 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 @@ -163,9 +186,6 @@ mkdir gen-kubectldocs/generators/v1_15 cp -r gen-kubectldocs/generators/v1_14/* gen-kubectldocs/generators/v1_15 ``` -The version directory is a staging area for the kubectl command reference build. -The YAML files are used to create the structure and navigation for the new reference. - ## Checking out a branch in k8s.io/kubernetes In your local repository, checkout the branch that has @@ -176,7 +196,7 @@ you local branch is up to date. ```shell cd git checkout release-1.15 -git pull https://github.com/k8s.io/kubernetes release-1.15 +git pull https://github.com/kubernetes/kubernetes release-1.15 ``` ## Running the doc generation code @@ -190,45 +210,59 @@ make copycli ``` The `copycli` command will clean the staging directories, generate the kubectl command files, -and copy the collated html page and assets to ``. +and copy the collated kubectl reference HTML page and assets to ``. ## Locate the generated files -These two files are the primary output of a successful build. Verify that they exist: +Verify that these two files have been generated: -* `/gen-kubectldocs/generators/build/index.html` -* `/gen-kubectldocs/generators/build/navData.js` +```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" +``` -## Locally test the documentation +## Locate the copied files -Build the Kubernetes documentation in your local ``. +Verify that all generated files have been copied to your ``: ```shell cd -make docker-serve +git status ``` -View the [local preview](/docs/reference/generated/kubectl/kubectl-cmds/) of the reference from: - -`https://localhost:1313` +The output should include the modified files: -## Adding and committing changes in kubernetes/website +``` +static/docs/reference/generated/kubectl/kubectl-commands.html +static/docs/reference/generated/kubectl/navData.js +``` -List the files that were generated and copied to the ``: +Additionally, the output might show the modified files: ``` -cd -git status +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 ``` -The output shows the new and modified files. For example, the output -might look like this: +## 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