Generating Reference Documentation for the Kubernetes API
This page shows how to update the Kubernetes API reference documentation.
The Kubernetes API reference documentation is built from the Kubernetes OpenAPI spec using the kubernetes-sigs/reference-docs generation code.
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
- Setting up the local repositories
- Generating the API reference docs
- Updating the API reference index pages
- Locally test the API reference
- Commit the changes
- What's next
Before you begin
Requirements:
You need a machine that is running Linux or macOS.
You need to have these tools installed:
Your
PATH
environment variable must include the required build tools, such as theGo
binary andpython
.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.
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-sigs/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
The base directory of your clone of the kubernetes/kubernetes repository is
$GOPATH/src/k8s.io/kubernetes.
The remaining steps refer to your base directory as<k8s-base>
.The base directory of your clone of the kubernetes/website repository is
$GOPATH/src/github.com/<your username>/website.
The remaining steps refer to your base directory as<web-base>
.The base directory of your clone of the kubernetes-sigs/reference-docs repository is
$GOPATH/src/github.com/kubernetes-sigs/reference-docs.
The remaining steps refer to your base directory as<rdocs-base>
.
Generating the API reference docs
This section shows how to generate the published Kubernetes API reference documentation.
Setting build variables
- Set
K8S_ROOT
to<k8s-base>
. - Set
WEB_ROOT
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.17, setK8S_RELEASE
to 1.17.
For example:
export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17
Creating versioned directory and fetching Open API spec
The updateapispec
build target creates the versioned build directory.
After the directory is created, the Open API spec is fetched from the
<k8s-base>
repository. These steps ensure that the version
of the configuration files and Kubernetes Open API spec match the release version.
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 updateapispec
Building the API reference docs
The copyapi
target builds the API reference and
copies the generated files to directories in <web-base>
.
Run the following command in <rdocs-base>
:
cd <rdocs-base>
make copyapi
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"
Go to the base of your local <web-base>
, and
view which files have been modified:
cd <web-base>
git status
The output is similar to:
static/docs/reference/generated/kubernetes-api/v1.17/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.17/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.17/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.17/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.17/index.html
static/docs/reference/generated/kubernetes-api/v1.17/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.17/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.17/js/scroll.js
Updating the API reference index pages
When generating reference documentation for a new release, update the file,
<web-base>/content/en/docs/reference/kubernetes-api/api-index.md
with the new
version number.
Open
<web-base>/content/en/docs/reference/kubernetes-api/api-index.md
for editing, and update the API reference version number. For example:--- title: v1.17 --- [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
Open
<web-base>/content/en/docs/reference/_index.md
for editing, and add a new link for the latest API reference. Remove the oldest API reference version. There should be five links to the most recent API references.
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
- Generating Reference Documentation Quickstart
- Generating Reference Docs for Kubernetes Components and Tools
- Generating Reference Documentation for kubectl Commands
Feedback
Was this page helpful?
Thanks for the feedback. If you have a specific, answerable question about how to use Kubernetes, ask it on Stack Overflow. Open an issue in the GitHub repo if you want to report a problem or suggest an improvement.