# Generating Reference Documentation for kubectl Commands

Generating Reference Documentation for kubectl CommandsThis page shows how to generate the kubectl command reference.Note:This topic shows how to generate reference documentation for kubectl commands like kubectl apply and kubectl taint. This topic does not show how to generate the kubectl options reference page. For instructions on how to generate the kubectl options reference page, see Generating Reference Pages for Kubernetes Components and Tools.Before you beginRequirements:You need a machine that is running Linux or macOS.You need to have these tools installed:Python v3.7.x+GitGolang version 1.13+Pip used to install PyYAMLPyYAML v5.1.2makegcc compiler/linkerDocker (Required only for kubectl command reference)Your PATH environment variable must include the required build tools, such as the Go binary and python.You need to know how to create a pull request to a GitHub repository. This involves creating your own fork of the repository. For more information, see Work from a local clone.Set up the local repositoriesCreate a local workspace and set your GOPATH:mkdir -p $HOME/<workspace> export GOPATH=$HOME/<workspace> Get 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 github.com/kubernetes-sigs/reference-docs If you don't already have the kubernetes/website repository, get it now:git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website 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: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 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 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 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 Kubernetes 1.33.0, you could use these commands:cd <k8s-base> git checkout v1.33.0 git pull https://github.com/kubernetes/kubernetes 1.33.0 If you do not need to edit the kubectl source code, follow the instructions for Setting build variables.Edit the kubectl source codeThe 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.PR 56673 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 pick your change into a release branchYour 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 1.34 and you want to backport your change to the release-1.33 branch. For instructions on how to do this, see Propose a Cherry Pick.Monitor your cherry-pick pull request until it is merged into the release branch.Note:Proposing a cherry pick requires that you have permission to set a label and a 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.Set build variablesGo 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 1.33, set K8S_RELEASE to 1.33.For example:export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes export K8S_RELEASE=1.33 Creating a versioned directoryThe createversiondirs build target creates a versioned directory and copies the kubectl reference configuration files to the versioned directory. The versioned directory name follows the pattern of v<major>_<minor>.In the <rdocs-base> directory, run the following build target:cd <rdocs-base> make createversiondirs Check out a release tag in k8s.io/kubernetesIn 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 1.33.0, check out the v1.33 tag. Make sure your local branch is up to date.cd <k8s-base> git checkout v1.33.0 git pull https://github.com/kubernetes/kubernetes v1.33.0 Run the doc generation codeIn your local <rdocs-base>, run the copycli build target. The command runs as root:cd <rdocs-base> make copycli The copycli command cleans the temporary build directory, generates the kubectl command files, and copies the collated kubectl command reference HTML page and assets to <web-base>.Locate the generated filesVerify that these two files have been generated:[ -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 filesVerify that all generated files have been copied to your <web-base>:cd <web-base> git status The output should include the modified files:static/docs/reference/generated/kubectl/kubectl-commands.html static/docs/reference/generated/kubectl/navData.js The output may also include: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 documentationBuild the Kubernetes documentation in your local <web-base>.cd <web-base> git submodule update --init --recursive --depth 1 # if not already done make container-serve View the local preview.Add and commit changes in kubernetes/websiteRun git add and git commit to commit the files.Create a pull requestCreate 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.What's nextGenerating Reference Documentation QuickstartGenerating Reference Documentation for Kubernetes Components and ToolsGenerating Reference Documentation for the Kubernetes API