kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

updating contrib for ref docs (#18787) 

more cleanup
pull/19018/head
Karen Bradshaw 2020-02-06 16:53:25 -05:00 committed by GitHub
parent 79e1b94c91
commit 121076085c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 433 additions and 385 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
content/en/docs/contribute/generate-ref-docs/_index.md
View File

@ -1,9 +1,12 @@
---
title: Reference docs overview
title: Reference Docs Overview
main_menu: true
weight: 80
---
Much of the Kubernetes reference documentation is generated from Kubernetes
source code, using scripts. The topics in this section document how to generate
this type of content.
The topics in this section document how to generate the Kubernetes
reference guides.
To build the reference documentation, see the following guide:
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)

40
content/en/docs/contribute/generate-ref-docs/contribute-upstream.md
View File

@ -1,13 +1,14 @@
---
title: Contributing to the Upstream Kubernetes Code
content_template: templates/task
weight: 20
---
{{% capture overview %}}
This page shows how to contribute to the upstream kubernetes/kubernetes project
to fix bugs found in the Kubernetes API documentation or the `kube-*`
components such as `kube-apiserver`, `kube-controller-manager`, etc.
This page shows how to contribute to the upstream `kubernetes/kubernetes` project.
You can fix bugs found in the Kubernetes API documentation or the content of
the Kubernetes components such as `kubeadm`, `kube-apiserver`, and `kube-controller-manager`.
If you instead want to regenerate the reference documentation for the Kubernetes
API or the `kube-*` components from the upstream code, see the following instructions:
@ -17,28 +18,25 @@ API or the `kube-*` components from the upstream code, see the following instruc
{{% /capture %}}
{{% capture prerequisites %}}
You need to have these tools installed:
- You need to have these tools installed:
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.9.1 or later
* [Docker](https://docs.docker.com/engine/installation/)
* [etcd](https://github.com/coreos/etcd/)
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Golang](https://golang.org/doc/install) version 1.13+
- [Docker](https://docs.docker.com/engine/installation/)
- [etcd](https://github.com/coreos/etcd/)
Your $GOPATH environment variable must be set, and the location of `etcd`
must be in your $PATH environment variable.
- Your `GOPATH` environment variable must be set, and the location of `etcd`
must be in your `PATH` environment variable.
You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
- You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository.
For more information, see [Creating a Pull Request](https://help.github.com/articles/creating-a-pull-request/)
and [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
{{% /capture %}}
{{% capture steps %}}
## The big picture
@ -221,11 +219,10 @@ the same as the generated files in the master branch. The generated files in the
contain API elements only from Kubernetes 1.9. The generated files in the master branch might contain
API elements that are not in 1.9, but are under development for 1.10.
## Generating the published reference docs
The preceding section showed how to edit a source file and then generate
several files, including `api/openapi-spec/swagger.json` in the
several files, including `api/openapi-spec/swagger.json` in the
`kubernetes/kubernetes` repository.
The `swagger.json` file is the OpenAPI definition file to use for generating
the API reference documentation.
@ -238,8 +235,7 @@ You are now ready to follow the [Generating Reference Documentation for the Kube
{{% capture whatsnext %}}
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
{{% /capture %}}

111
content/en/docs/contribute/generate-ref-docs/kubectl.md
View File

@ -1,12 +1,12 @@
---
title: Generating Reference Documentation for kubectl Commands
content_template: templates/task
weight: 90
---
{{% capture overview %}}
This page shows how to automatically generate reference pages for the
commands provided by the `kubectl` tool.
This page shows how to generate the `kubectl` command reference.
{{< note >}}
This topic shows how to generate reference documentation for
@ -23,29 +23,12 @@ reference page, see
{{% /capture %}}
{{% capture prerequisites %}}
* You need to have
[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
installed.
* You need to have
[Golang](https://golang.org/doc/install) version 1.9.1 or later installed,
and your `$GOPATH` environment variable must be set.
* You need to have
[Docker](https://docs.docker.com/engine/installation/) installed.
* You need to know how to create a pull request to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
{{< include "prerequisites-ref-docs.md" >}}
{{% /capture %}}
{{% capture steps %}}
## Setting up the local repositories
@ -85,8 +68,7 @@ Remove the spf13 package from `$GOPATH/src/k8s.io/kubernetes/vendor/github.com`.
rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13
```
The kubernetes/kubernetes repository provides access to the kubectl and kustomize source code.
The kubernetes/kubernetes repository provides the `kubectl` and `kustomize` source code.
* Determine the base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
@ -108,15 +90,16 @@ The remaining steps refer to your base directory as `<rdocs-base>`.
In your local k8s.io/kubernetes repository, check out the branch of interest,
and make sure it is up to date. For example, if you want to generate docs for
Kubernetes 1.15, you could use these commands:
Kubernetes 1.17, you could use these commands:
```shell
cd <k8s-base>
git checkout release-1.15
git pull https://github.com/kubernetes/kubernetes release-1.15
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0
```
If you do not need to edit the kubectl source code, follow the instructions to [Edit the Makefile](#editing-makefile).
If you do not need to edit the `kubectl` source code, follow the instructions for
[Setting build variables](#setting-build-variables).
## Editing the kubectl source code
@ -152,65 +135,60 @@ milestone in your pull request. If you don’t have those permissions, you will
need to work with someone who can set the label and milestone for you.
{{< /note >}}
## Editing Makefile
## Setting build variables
Go to `<rdocs-base>`, and open the `Makefile` for editing:
Go to `<rdocs-base>`. On you command line, set the following environment variables.
* Set `K8SROOT` to `<k8s-base>`.
* Set `WEBROOT` to `<web-base>`.
* Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
* 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, set `K8S_RELEASE` to 1.17.
For example, update the following variables:
```
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15
```
## Creating a version directory
The version directory is a staging area for the kubectl command reference build.
The YAML files in this directory are used to create the structure and navigation
of the kubectl command reference.
In the `<rdocs-base>/gen-kubectldocs/generators` directory, if you do not already
have a directory named `v1_<MINOR_VERSION>`, create one now by copying the directory
for the previous version. For example, suppose you want to generate docs for
Kubernetes 1.15, but you don't already have a `v1_15` directory. Then you could
create and populate a `v1_15` directory by running these commands:
For example:
```shell
mkdir gen-kubectldocs/generators/v1_15
cp -r gen-kubectldocs/generators/v1_14/* gen-kubectldocs/generators/v1_15
export WEB_ROOT=$(GOPATH)/src/github.com/<your-username>/website
export K8S_ROOT=$(GOPATH)/src/k8s.io/kubernetes
export K8S_RELEASE=1.17
```
## Checking out a branch in k8s.io/kubernetes
## Creating a versioned directory
In your local <k8s-base> repository, checkout the branch that has
The `createversiondirs` build target creates a versioned directory
and copies the kubectl reference configuration files to the versioned directory.
The versioned directory name follows the pattern of `v<major>_<minor>`.
In the `<rdocs-base>` directory, run the following build target:
```shell
cd <rdocs-base>
make createversiondirs
```
## Checking out a release tag in k8s.io/kubernetes
In your local `<k8s-base>` repository, checkout the branch that has
the version of Kubernetes that you want to document. For example, if you want
to generate docs for Kubernetes 1.15, checkout the release-1.15 branch. Make sure
to generate docs for Kubernetes 1.17, checkout the `v1.17.0` tag. Make sure
you local branch is up to date.
```shell
cd <k8s-base>
git checkout release-1.15
git pull https://github.com/kubernetes/kubernetes release-1.15
git checkout v1.17.0
git pull https://github.com/kubernetes/kubernetes v1.17.0
```
## Running the doc generation code
In your local kubernetes-sigs/reference-docs repository, build and run the
kubectl command reference generation code. You might need to run the command as root:
In your local `<rdocs-base>`, run the `copycli` build target. The command runs as `root`:
```shell
cd <rdocs-base>
make copycli
```
The `copycli` command will clean the staging directories, generate the kubectl command files,
and copy the collated kubectl reference HTML page and assets to `<web-base>`.
The `copycli` command cleans the temporary build directory, generates the kubectl command files,
and copies the collated kubectl command reference HTML page and assets to `<web-base>`.
## Locate the generated files
@ -237,7 +215,7 @@ static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
```
Additionally, the output might show the modified files:
The output may also include:
```
static/docs/reference/generated/kubectl/scroll.js
@ -275,13 +253,12 @@ 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 %}}
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for the Kubernetes API](/docs/contribute/generate-ref-docs/kubernetes-api/)
{{% /capture %}}

148
content/en/docs/contribute/generate-ref-docs/kubernetes-api.md
View File

@ -1,14 +1,16 @@
---
title: Generating Reference Documentation for the Kubernetes API
content_template: templates/task
weight: 50
---
{{% capture overview %}}
This page shows how to update the generated reference docs 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](https://github.com/kubernetes/kubernetes/blob/master/api/openapi-spec/swagger.json)
and tools from [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs).
using the [kubernetes-sigs/reference-docs](https://github.com/kubernetes-sigs/reference-docs) generation code.
If you find bugs in the generated documentation, you need to
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).
@ -18,23 +20,12 @@ spec, continue reading this page.
{{% /capture %}}
{{% capture prerequisites %}}
You need to have these tools installed:
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.9.1 or later
You need to know how to create a pull request (PR) to a GitHub repository.
Typically, this involves creating a fork of the repository. For more
information, see
[Creating a Documentation Pull Request](/docs/contribute/start/) and
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
{{< include "prerequisites-ref-docs.md" >}}
{{% /capture %}}
{{% capture steps %}}
## Setting up the local repositories
@ -83,49 +74,50 @@ The remaining steps refer to your base directory as `<web-base>`.
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](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
### Modifying the Makefile
### Setting build variables
Go to `<rdocs-base>`, and open the `Makefile` for editing:
* 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, set `K8S_RELEASE` to 1.17.
* Set `K8SROOT` to `<k8s-base>`.
* Set `WEBROOT` to `<web-base>`.
* Set `MINOR_VERSION` to the minor version of the docs you want to build. For example,
if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
For example, update the following variables:
```
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15
```
### Copying the OpenAPI spec
Run the following command in `<rdocs-base>`:
For example:
```shell
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:
```shell
cd <rdocs-base>
make updateapispec
```
The output shows that the file was copied:
```shell
cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
```
### 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>`:
```shell
make api
cd <rdocs-base>
make copyapi
```
Verify that these two files have been generated:
@ -135,71 +127,57 @@ Verify that these two files have been generated:
[ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"
```
### Creating directories for published docs
Create the directories in `<web-base>` for the generated API reference files:
```shell
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/css
mkdir -p <web-base>/static/docs/reference/generated/kubernetes-api/v1.<minor-version>/fonts
```
## Copying the generated docs to the kubernetes/website repository
Run the following command in `<rdocs-base>` to copy the generated files to
your local kubernetes/website repository:
```shell
make copyapi
```
Go to the base of your local kubernetes/website repository, and
see which files have been modified:
Go to the base of your local `<web-base>`, and
view which files have been modified:
```shell
cd <web-base>
git status
```
The output shows the modified files:
The output is similar to:
```
static/docs/reference/generated/kubernetes-api/v1.15/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.15/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.15/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.15/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.15/index.html
static/docs/reference/generated/kubernetes-api/v1.15/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.15/navData.js
static/docs/reference/generated/kubernetes-api/v1.15/scroll.js
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
* Open `<web-base>/content/en/docs/reference/kubernetes-api/api-index.md` for editing, and update the API reference version number. For example:
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.
```markdown
* 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.15
title: v1.17
---
[Kubernetes API v1.15](/docs/reference/generated/kubernetes-api/v1.15/)
[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.
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](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/).
Verify the [local preview](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.17/).
```shell
cd <web-base>
@ -220,8 +198,8 @@ to monitor your pull request until it has been merged.
{{% capture whatsnext %}}
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [Generating Reference Docs for Kubernetes Components and Tools](/docs/contribute/generate-ref-docs/kubernetes-components/)
* [Generating Reference Documentation for kubectl Commands](/docs/contribute/generate-ref-docs/kubectl/)
{{% /capture %}}

210
content/en/docs/contribute/generate-ref-docs/kubernetes-components.md
View File

@ -1,228 +1,34 @@
---
title: Generating Reference Pages for Kubernetes Components and Tools
content_template: templates/task
weight: 120
---
{{% capture overview %}}
This page shows how to use the `update-imported-docs` tool to generate
reference documentation for tools and components in the
[Kubernetes](https://github.com/kubernetes/kubernetes) repository.
This page shows how to build the Kubernetes component and tool reference pages.
{{% /capture %}}
{{% capture prerequisites %}}
* You need a machine that is running Linux or macOS.
* Install the following:
* [Python](https://www.python.org/downloads/) v3.7.x
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.13+
* [Pip](https://pypi.org/project/pip/) used to install PyYAML
* [PyYAML](https://pyyaml.org/) v5.1.2
* [make](https://www.gnu.org/software/make/)
* [gcc compiler/linker](https://gcc.gnu.org/)
* The `Go` binary must be in your path. The `update-imported-docs` tool 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](/docs/contribute/intermediate/#work_from_a_local_clone).
Start with the [Prerequisites section](/docs/contribute/generate-ref-docs/quickstart/#before-you-begin)
in the Reference Documentation Quickstart guide.
{{% /capture %}}
{{% capture steps %}}
## Getting the repository
Make sure your `website` fork is up-to-date with the `kubernetes/website` master and then 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>`.
The `update-imported-docs` tool generates the reference documentation for the
Kubernetes components from the Kubernetes source code. The tool automatically
clones the `kubernetes/kubernetes` repository. If you want to change the
reference documentation, please follow [this
guide](/docs/contribute/generate-ref-docs/contribute-upstream).
## Overview of update-imported-docs
The `update-imported-docs` tool is located in the `kubernetes/website/update-imported-docs/`
directory. The tool consists of a Python script that reads a YAML configuration file and 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 Markdown files.
1. Copies the generated Markdown files to a local clone of the `kubernetes/website`
repository under locations specified in the configuration file.
1. Updates `kubectl` command links from `kubectl`.md to the `kubectl` command reference.
When the Markdown files are in your local clone of the `kubernetes/website`
repository, you can submit them in a [pull request](/docs/contribute/start/)
to `kubernetes/website`.
## 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:
1. Adhere to the [Documentation Style Guide](/docs/contribute/style/style-guide/).
1. Have `title` defined in the front matter. For example:
```
---
title: Title Displayed in Table of Contents
---
Rest of the .md file...
```
1. Be listed in the `kubernetes/website/data/reference.yml` file
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
```
Note: `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
Open `<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.
```yaml
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 `src` and `dst` fields. The `src` field
specifies the location of a generated Markdown file, 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` and you can just 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
After having reviewed and/or customized the `reference.yaml` file, you can run
the `update-imported-docs` tool:
```shell
cd <web-base>/update-imported-docs
./update-imported-docs reference.yml
```
## Fixing Links
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
[`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 the `kubernetes/website`
repository:
```
cd <web-base>
git status
```
The output shows the new and modified files. For example, the output
might look like this:
```shell
...
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
...
```
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/).
Follow the [Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
to generate the Kubernetes component and tool reference pages.
{{% /capture %}}
{{% capture whatsnext %}}
* [Generating Reference Documentation Quickstart](/docs/contribute/generate-ref-docs/quickstart/)
* [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/)
* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/generate-ref-docs/contribute-upstream/)
{{% /capture %}}

21
content/en/docs/contribute/generate-ref-docs/prerequisites-ref-docs.md Normal file
View File

@ -0,0 +1,21 @@
### Requirements:
- You need a machine that is running Linux or macOS.
- You need to have these tools installed:
- [Python](https://www.python.org/downloads/) v3.7.x
- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- [Golang](https://golang.org/doc/install) version 1.13+
- [Pip](https://pypi.org/project/pip/) used to install PyYAML
- [PyYAML](https://pyyaml.org/) v5.1.2
- [make](https://www.gnu.org/software/make/)
- [gcc compiler/linker](https://gcc.gnu.org/)
- [Docker](https://docs.docker.com/engine/installation/) (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](/docs/contribute/intermediate/#work_from_a_local_clone).

260
content/en/docs/contribute/generate-ref-docs/quickstart.md Normal file
View File

@ -0,0 +1,260 @@
---
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 %}}

17
update-imported-docs/README.md
View File

@ -1,12 +1,19 @@
### Update Kubernetes reference docs
This `update-imported-docs.py` script generates the Kubernetes reference docs (component/tool pages, kubectl-command, Kubernetes API reference).
The `update-imported-docs` script generates the Kubernetes reference docs (component and tool pages, kubectl-command
reference, and Kubernetes API reference).
<!-- TODO: Update this information -->
[Generating Reference Pages for Kubernetes Components and Tools](https://kubernetes.io/docs/contribute/generate-ref-docs/kubernetes-components/) contains detailed instructions for using this tool.
For detailed information about the generation process, view the
[Generating Reference Documentation Quickstart Guide](https://kubernetes.io/docs/contribute/generate-ref-docs/quickstart/).
### General Usage
```shell
python3 update-imported-docs.py <config_file> <k8s_release>
```
./update-imported-docs <configuration-file.yml> <k8s_release>
```
For example:
```shell
./update-imported-docs reference.yml 1.17
```