# Reference Documentation Quickstart

Reference Documentation QuickstartThis 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 beginRequirements:You need a machine that is running Linux or macOS.You need to have these tools installed:Python v3.7.x+GitGolang version 1.13+Pip used to install PyYAMLPyYAML v5.1.2makegcc compiler/linkerDocker (Required only for kubectl command reference)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 repositoryMake 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>.Note:If you want to change the content of the component tools and API reference, see the contributing upstream guide.Overview of update-imported-docsThe 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 pagesThe kubectl command referenceThe Kubernetes API referenceNote:The kubelet reference page is not generated by this script and is maintained manually. To update the kubelet reference, follow the standard contribution process described in Opening a pull request.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_RELEASEK8S_ROOTK8S_WEBROOTThe script requires two arguments to run successfully:A YAML configuration file (reference.yml)A release version, for example:1.17The 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: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.Runs commands under the cloned repositories to prepare the docs generator and then generates the HTML and Markdown files.Copies the generated HTML and Markdown files to a local clone of the <web-base> repository under locations specified in the configuration file.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 formatEach 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.ymlOpen <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.Note:The 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 repository.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 toolYou 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 Fixing LinksThe 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/websiteList 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 filescontent/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 filesstatic/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 filesstatic/docs/reference/generated/kubernetes-api/v1.34/index.html static/docs/reference/generated/kubernetes-api/v1.34/js/navData.js static/docs/reference/generated/kubernetes-api/v1.34/js/scroll.js static/docs/reference/generated/kubernetes-api/v1.34/js/query.scrollTo.min.js static/docs/reference/generated/kubernetes-api/v1.34/css/font-awesome.min.css static/docs/reference/generated/kubernetes-api/v1.34/css/bootstrap.min.css static/docs/reference/generated/kubernetes-api/v1.34/css/stylesheet.css static/docs/reference/generated/kubernetes-api/v1.34/fonts/FontAwesome.otf static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.eot static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.svg static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.ttf static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.woff static/docs/reference/generated/kubernetes-api/v1.34/fonts/fontawesome-webfont.woff2 Run git add and git commit to commit the files.Creating a pull requestCreate 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 nextTo generate the individual reference documentation by manually setting up the required build repositories and running the build targets, see the following guides:Generating Reference Documentation for Kubernetes Components and ToolsGenerating Reference Documentation for kubectl CommandsGenerating Reference Documentation for the Kubernetes API