Generating Reference Documentation for kubectl Commands
This page shows how to automatically generate reference pages for the
commands provided by the kubectl tool.
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 begin
- Getting three repositories
- Editing the kubectl source code
- Cherry picking your change into a release branch
- Editing Makefile
- Building the brodocs image
- Creating a version directory
- Checking out a branch in kubernetes/kubernetes
- Running the doc generation code
- Locate the generated files
- Copying files to the kubernetes/website repository
- Adding and committing changes in kubernetes/website
- Creating a pull request
- What's next
Before you begin
You need to have Git installed.
You need to have Golang version 1.9.1 or later installed, and your
$GOPATHenvironment variable must be set.You need to have Docker installed.
You need to know how to create a pull request to a GitHub repository. Typically, this involves creating a fork of the repository. For more information, see Creating a Documentation Pull Request and GitHub Standard Fork & Pull Request Workflow.
Getting three repositories
If you don’t already have the kubernetes/kubernetes repository, get it now:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetesDetermine 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/github.com/kubernetes/kubernetes.
The remaining steps refer to your base directory as <k8s-base>.
If you don’t already have the kubernetes/website repository, get it now:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/websiteDetermine 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/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:
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docsDetermine the base directory of your clone of the
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, 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:
cd <k8s-base>
git checkout release-1.9
git pull https://github.com/kubernetes/kubernetes release-1.9Editing 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 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 master branch of the kubernetes/kubernetes repository.
Cherry picking your change into a release branch
Your 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.10, and you want to backport your change to the release-1.9 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.
Editing Makefile
Go to <rdocs-base>, 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.
make brodocsVerify that you have the brodocs image:
docker imagesThe output shows pwittrock/brodocs as one of the available images:
REPOSITORY TAG IMAGE ID CREATED SIZE
pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MBCreating 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
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:
mkdir gen-kubectldocs/generators/v1_9
cp -r gen-kubectldocs/generators/v1_8/* gen-kubectldocs/generators/v1_9Checking out a branch in kubernetes/kubernetes
In you local kubernetes/kubernetes 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 you local branch is up to date.
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:
cd <rdocs-base>
make cliLocate 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.
cd <rdocs-base>
make copycliAdding and committing changes in kubernetes/website
List the files that were generated and copied to the kubernetes/website
repository:
cd <web-base>
git status
The output shows the new and modified files. For example, the output might look like this:
modified: docs/reference/generated/kubectl/kubectl-commands.html
modified: docs/reference/generated/kubectl/navData.jsRun git add and git commit to commit the files.
Creating a pull request
Create 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.