Learn Kubernetes Basics

Contribute to Kubernetes docs

Kubernetes v1.14 documentation is no longer actively maintained. The version you are currently viewing is a static snapshot. For up-to-date documentation, see the latest version.

Edit This Page

Generating Reference Documentation for the Kubernetes API

This page shows how to update the generated reference docs for the Kubernetes API.

Before you begin

You need to have these tools installed:

Your $GOPATH environment variable must be set.

You need to know how to create a pull request (PR) 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.

The big picture

The reference documentation for the Kubernetes API is generated in two separate stages:

  1. Generate an OpenAPI spec from the Kubernetes source code. The tools for this stage are at kubernetes/kubernetes/hack.

  2. Generate an HTML file from the OpenAPI spec. The tools for this stage are at kubernetes-incubator/reference-docs.

If you find bugs in the generated documentation generated, you need to fix them upstream.

If you need only to regenerate the reference documentation from the OpenAPI spec, continue reading this page.

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/kubernetes

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/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/website

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/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-docs

Determine 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>.

Generating the API reference docs for publishing

The preceding section showed how to edit a source file and then generate several files, including api/openapi-spec/swagger.json in the kubernetes/kubernetes repository.

This section shows how to generate the published Kubernetes API reference documentation, which is generated by the tools at kubernetes-incubator/reference-docs. Those tools take the api/openapi-spec/swagger.json file as input.

Editing Makefile in kubernetes-incubator/reference-docs

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.

Copying the OpenAPI spec

The doc generation code needs a local copy of the OpenAPI spec for the Kubernetes API. Go to <k8s-base> and check out the branch that has the OpenAPI spec you want to use. For example, if you want to generate docs for Kubernetes 1.9, checkout the release-1.9 branch.

Go back to <rdocs-base>. Enter the following command to copy the OpenAPI spec from the kubernetes/kubernetes repository to a local directory:

make updateapispec

The output shows that the file was copied:

cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json

Building the API reference docs

Run the following command to generate the API reference docs:

cd <rdocs-base>
make api

Locate the generated files

These two files are the output of a successful build. Verify that they exist:

Copying the generated docs to the kubernetes/website repository

The preceding sections showed how to generate reference documentation for publication.

This section shows how to copy the generated reference to the kubernetes/website repository. The files in the kubernetes/website repository are published in the kubernetes.io website. In particular, the generated index.html file is published here.

Enter the following command to copy the generated files to your local kubernetes/website repository:

make copyapi

Go to the base of your local kubernetes/website repository, and see which files have been modified:

cd <web-base>
git status

The output shows the modified files:

On branch master
...
   modified:   docs/reference/generated/kubernetes-api/v1.9/index.html

In this example, only one file has been modified. Recall that you generated both index.html and navData.js. But apparently the generated navata.js is not different from the navData.js that was already in the kubernetes/website` repository.

In <web-base> run git add and git commit to commit the change.

Submit your changes as a pull request to the kubernetes/website repository. Monitor your pull request, and respond to reviewer comments as needed. Continue to monitor your pull request until it has been merged.

A few minutes after your pull request is merged, your changes will be visible in the published reference documentation.

What's next

Feedback