261 lines
9.6 KiB
Markdown
261 lines
9.6 KiB
Markdown
---
|
|
title: Quickstart
|
|
content_template: templates/task
|
|
weight: 40
|
|
---
|
|
|
|
{{% capture overview %}}
|
|
|
|
This page shows how to use the `update-imported-docs` script to generate
|
|
the Kubernetes reference documentation. The script automates
|
|
the build setup and generates the reference documentation for a release.
|
|
|
|
{{% /capture %}}
|
|
|
|
{{% capture prerequisites %}}
|
|
|
|
{{< include "prerequisites-ref-docs.md" >}}
|
|
|
|
{{% /capture %}}
|
|
|
|
{{% capture steps %}}
|
|
|
|
## Getting the docs repository
|
|
|
|
Make sure your `website` fork is up-to-date with the `kubernetes/website` master and clone
|
|
your `website` fork.
|
|
|
|
```shell
|
|
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](/docs/contribute/generate-ref-docs/contribute-upstream).
|
|
{{< /note >}}
|
|
|
|
## Overview of update-imported-docs
|
|
|
|
The `update-imported-docs` 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` 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` 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`.
|
|
1. Runs commands under the cloned repositories to prepare the docs generator and
|
|
then generates the HTML and Markdown files.
|
|
1. Copies the generated HTML and Markdown files to a local clone of the `<web-base>`
|
|
repository under locations specified in the configuration file.
|
|
1. 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](/docs/contribute/start/)
|
|
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:
|
|
|
|
```yaml
|
|
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](/docs/contribute/style/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](https://kubernetes.slack.com).
|
|
|
|
{{< 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.
|
|
{{< /note >}}
|
|
|
|
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:
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
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` tool as follows:
|
|
|
|
```shell
|
|
cd <web-base>/update-imported-docs
|
|
./update-imported-docs <configuration-file.yml> <release-version>
|
|
```
|
|
|
|
For example:
|
|
|
|
```shell
|
|
./update-imported-docs reference.yml 1.17
|
|
```
|
|
|
|
<!-- Revisit: is the release configuration used -->
|
|
## Fixing Links
|
|
|
|
The `release.yml` configuration file contains instructions to fix relative links.
|
|
To fix relative links within your imported files, set the`gen-absolute-links`
|
|
property to `true`. You can find an example of this in
|
|
[`release.yml`](https://github.com/kubernetes/website/blob/master/update-imported-docs/release.yml).
|
|
|
|
## Adding and committing changes in kubernetes/website
|
|
|
|
List the files that were generated and copied to `<web-base>`:
|
|
|
|
```shell
|
|
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.17/index.html
|
|
static/docs/reference/generated/kubernetes-api/v1.17/js/navData.js
|
|
static/docs/reference/generated/kubernetes-api/v1.17/js/scroll.js
|
|
static/docs/reference/generated/kubernetes-api/v1.17/js/query.scrollTo.min.js
|
|
static/docs/reference/generated/kubernetes-api/v1.17/css/font-awesome.min.css
|
|
static/docs/reference/generated/kubernetes-api/v1.17/css/bootstrap.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
|
|
```
|
|
|
|
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](/docs/home/).
|
|
|
|
{{% /capture %}}
|
|
|
|
{{% capture whatsnext %}}
|
|
|
|
To 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 Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
|
|
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
|
|
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
|
|
|
|
{{% /capture %}}
|