Reference Documentation Quickstart

This page shows how to use the update-imported-docs.py script to generate the Kubernetes reference documentation. The script automates the build setup and generates the reference documentation for a release.

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

Getting the docs repository

Make sure your website fork is up-to-date with the kubernetes/website remote on GitHub (main branch), and clone your website fork.

mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git

Determine the base directory of your clone. For example, if you followed the preceding step to get the repository, your base directory is github.com/website. The remaining steps refer to your base directory as <web-base>.

Overview of update-imported-docs

The update-imported-docs.py script is located in the <web-base>/update-imported-docs/ directory.

The script builds the following references:

  • Component and tool reference pages
  • The kubectl command reference
  • The Kubernetes API reference

The update-imported-docs.py script generates the Kubernetes reference documentation from the Kubernetes source code. The script creates a temporary directory under /tmp on your machine and clones the required repositories: kubernetes/kubernetes and kubernetes-sigs/reference-docs into this directory. The script sets your GOPATH to this temporary directory. Three additional environment variables are set:

  • K8S_RELEASE
  • K8S_ROOT
  • K8S_WEBROOT

The script requires two arguments to run successfully:

  • A YAML configuration file (reference.yml)
  • A release version, for example:1.17

The configuration file contains a generate-command field. The generate-command field defines a series of build instructions from kubernetes-sigs/reference-docs/Makefile. The K8S_RELEASE variable determines the version of the release.

The update-imported-docs.py script performs the following steps:

  1. Clones the related repositories specified in a configuration file. For the purpose of generating reference docs, the repository that is cloned by default is kubernetes-sigs/reference-docs.
  2. Runs commands under the cloned repositories to prepare the docs generator and then generates the HTML and Markdown files.
  3. Copies the generated HTML and Markdown files to a local clone of the <web-base> repository under locations specified in the configuration file.
  4. Updates kubectl command links from kubectl.md to the refer to the sections in the kubectl command reference.

When the generated files are in your local clone of the <web-base> repository, you can submit them in a pull request to <web-base>.

Configuration file format

Each configuration file may contain multiple repos that will be imported together. When necessary, you can customize the configuration file by manually editing it. You may create new config files for importing other groups of documents. The following is an example of the YAML configuration file:

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

Single page Markdown documents, imported by the tool, must adhere to the Documentation Style Guide.

Customizing reference.yml

Open <web-base>/update-imported-docs/reference.yml for editing. Do not change the content for the generate-command field unless you understand how the command is used to build the references. You should not need to update reference.yml. At times, changes in the upstream source code, may require changes to the configuration file (for example: golang version dependencies and third-party library changes). If you encounter build issues, contact the SIG-Docs team on the #sig-docs Kubernetes Slack channel.

In reference.yml, files contains a list of src and dst fields. The src field contains the location of a generated Markdown file in the cloned kubernetes-sigs/reference-docs build directory, and the dst field specifies where to copy this file in the cloned kubernetes/website repository. For example:

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

Note that when there are many files to be copied from the same source directory to the same destination directory, you can use wildcards in the value given to src. You must provide the directory name as the value for dst. For example:

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

Running the update-imported-docs tool

You can run the update-imported-docs.py tool as follows:

cd <web-base>/update-imported-docs
./update-imported-docs.py <configuration-file.yml> <release-version>

For example:

./update-imported-docs.py reference.yml 1.17

The release.yml configuration file contains instructions to fix relative links. To fix relative links within your imported files, set thegen-absolute-links property to true. You can find an example of this in release.yml.

Adding and committing changes in kubernetes/website

List the files that were generated and copied to <web-base>:

cd <web-base>
git status

The output shows the new and modified files. The generated output varies depending upon changes made to the upstream source code.

Generated component tool files

content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

Generated kubectl command reference files

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
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/css/font-awesome.min.css

Generated Kubernetes API reference directories and files

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

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

What's next

To generate the individual reference documentation by manually setting up the required build repositories and running the build targets, see the following guides:

Last modified October 27, 2022 at 3:04 PM PST: Tweak reference docs section index (3c33ffc914)