Generating Reference Pages for Kubernetes Components and Tools
This page shows how to use the
update-imported-docs tool to generate
reference documentation for tools and components in the
- Before you begin
- Getting the repository
- Overview of update-imported-docs
- Configuration file format
- Customizing the reference.yml config file
- Running the update-imported-docs tool
- Fixing Links
- Adding and committing changes in kubernetes/website
- Creating a pull request
- What's next
Before you begin
You need a machine that is running Linux or macOS.
Install the following:
Gobinary must be in your path. The
update-imported-docstool sets your GOPATH.
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 repository
Make sure your
website fork is up-to-date with the
kubernetes/website master and then clone your
mkdir github.com cd github.com git clone firstname.lastname@example.org:<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
update-imported-docs tool generates the reference documentation for the
Kubernetes components from the Kubernetes source code. The tool automatically
kubernetes/kubernetes repository. If you want to change the
reference documentation, please follow this
Overview of update-imported-docs
update-imported-docs tool is located in the
directory. The tool consists of a Python script that reads a YAML configuration file and performs the following steps:
- Clones the related repositories specified in a configuration file. For the
purpose of generating reference docs, the repository that is cloned by
- Runs commands under the cloned repositories to prepare the docs generator and then generates the Markdown files.
- Copies the generated Markdown files to a local clone of the
kubernetes/websiterepository under locations specified in the configuration file.
kubectlcommand links from
kubectl.md to the
When the Markdown files are in your local clone of the
repository, you can submit them in a pull request
Configuration file format
Each config 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. Imported documents must follow these guidelines:
Adhere to the Documentation Style Guide.
titledefined in the front matter. For example:
--- title: Title Displayed in Table of Contents --- Rest of the .md file...
Be listed in the
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
generate-command is an optional entry, which can be used to run a
given command or a short script to generate the docs from within a repo.
Customizing the reference.yml config file
<web-base>/update-imported-docs/reference.yml for editing.
Do not change the content for the
generate-command entry unless you understand
what it is doing and need to change the specified release branch.
repos: - name: reference-docs remote: https://github.com/kubernetes-sigs/reference-docs.git # This and the generate-command below needs a change when reference-docs has # branches properly defined branch: master generate-command: | cd $GOPATH git clone https://github.com/kubernetes/kubernetes.git src/k8s.io/kubernetes cd src/k8s.io/kubernetes git checkout release-1.17 make generated_files cp -L -R vendor $GOPATH/src rm -r vendor cd $GOPATH go get -v github.com/kubernetes-sigs/reference-docs/gen-compdocs cd src/github.com/kubernetes-sigs/reference-docs/ make comp
In reference.yml, the
files field is a list of
dst fields. The
specifies the location of a generated Markdown file, and the
dst field specifies
where to copy this file in the cloned
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 and you can just provide the directory name as the value for
files: - src: gen-compdocs/build/kubeadm*.md dst: content/en/docs/reference/setup-tools/kubeadm/generated/
Running the update-imported-docs tool
After having reviewed and/or customized the
reference.yaml file, you can run
cd <web-base>/update-imported-docs ./update-imported-docs reference.yml
To fix relative links within your imported files, set the repo config’s
gen-absolute-links property to
true. You can find an example of this in
Adding and committing changes in kubernetes/website
List the files that were generated and copied to the
cd <web-base> git status
The output shows the new and modified files. For example, the output might look like this:
... modified: content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md modified: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md modified: content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md modified: content/en/docs/reference/command-line-tools-reference/kube-proxy.md modified: content/en/docs/reference/command-line-tools-reference/kube-scheduler.md modified: content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md modified: content/en/docs/reference/kubectl/kubectl.md ...
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.
- Generating Reference Documentation for kubectl Commands
- Generating Reference Documentation for the Kubernetes API
- Contributing to the Upstream Kubernetes Project for Documentation
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.