Contribute to Kubernetes docs

Kubernetes v1.15 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. The Kubernetes API reference documentation is built from the Kubernetes OpenAPI spec and tools from kubernetes-incubator/reference-docs.

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

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

Before you begin

You need to have these tools installed:

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.

Setting up the local repositories

Create 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/kubernetes-incubator/reference-docs

go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec

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

Generating the API reference docs

This section shows how to generate the published Kubernetes API reference documentation.

Modifying the Makefile

Go to <rdocs-base>, and open the Makefile for editing:

For example, update the following variables:

WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15

Copying the OpenAPI spec

Run the following command in <rdocs-base>:

make updateapispec

The output shows that the file was copied:

cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json

Building the API reference docs

Run the following command in <rdocs-base>:

make api

Verify that these two files have been generated:

[ -e "<rdocs-base>/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Creating directories for published docs

Create the directories in <web-base> for the generated API reference files:

mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/css
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/fonts

Copying the generated docs to the kubernetes/website repository

Run the following command in <rdocs-base> 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:

static/docs/reference/generated/kubernetes-api/v1.15/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.15/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.15/index.html
static/docs/reference/generated/kubernetes-api/v1.15/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.15/navData.js
static/docs/reference/generated/kubernetes-api/v1.15/scroll.js

Updating the API reference index pages

Locally test the API reference

Publish a local version of the API reference. Verify the local preview.

cd <web-base>
make docker-serve

Commit the changes

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.

What's next

Feedback