307 lines
11 KiB
Markdown
307 lines
11 KiB
Markdown
|
---
|
|||
|
|
title: Generating Reference Pages for Kubernetes Components and Tools
|
|||
|
content_template: templates/task
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
{{% 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) and
|
|||
|
|
[Federation](https://github.com/kubernetes/federation) repositories.
|
|||
|
|
|
|||
|
|
{{% /capture %}}
|
|||
|
|
|
|||
|
|
|
|||
|
|
{{% capture prerequisites %}}
|
|||
|
|
|
|||
|
* You need a machine that is running Linux or macOS.
|
|||
|
|
|
|||
|
|
* You need to have this software installed:
|
|||
|
|
|
|||
|
|
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
|
|||
|
|
|
|||
|
|
* [Golang](https://golang.org/doc/install) version 1.9 or later
|
|||
|
|
|
|||
|
|
* [make](https://www.gnu.org/software/make/)
|
|||
|
|
|
|||
|
|
* [gcc compiler/linker](https://gcc.gnu.org/)
|
|||
|
|
|
|||
|
|
* Your `$GOPATH` environment variable must be set.
|
|||
|
|
|
|||
|
|
* 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/).
|
|||
|
|
|
|||
|
|
{{% /capture %}}
|
|||
|
|
|
|||
|
|
|
|||
|
|
{{% capture steps %}}
|
|||
|
|
|
|||
|
|
## Getting two repositories
|
|||
|
|
|
|||
|
|
If you don't already have the `kubernetes/website` repository, get it now:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
mkdir $GOPATH/src
|
|||
|
|
cd $GOPATH/src
|
|||
|
|
go get github.com/kubernetes/website
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Determine the base directory of your clone of the
|
|||
|
|
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
|||
|
|
For example, if you followed the preceding step to get the repository,
|
|||
|
|
your base directory is `$GOPATH/src/github.com/kubernetes/website.`
|
|||
|
|
The remaining steps refer to your base directory as `<web-base>`.
|
|||
|
|
|
|||
|
|
If you plan on making changes to the ref docs, and if you don't already have
|
|||
|
|
the `kubernetes/kubernetes` repository, get it now:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
mkdir $GOPATH/src
|
|||
|
|
cd $GOPATH/src
|
|||
|
|
go get github.com/kubernetes/kubernetes
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Determine the base directory of your clone of the
|
|||
|
|
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
|
|||
|
|
For example, if you followed the preceding step to get the repository,
|
|||
|
|
your base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.`
|
|||
|
|
The remaining steps refer to your base directory as `<k8s-base>`.
|
|||
|
|
|
|||
|
|
{{< note >}}
|
|||
|
|
**Note:**
|
|||
|
|
If you only need to generate, but not change, the reference docs, you don't need to
|
|||
|
|
manually get the `kubernetes/kubernetes` repository. When you run the `update-imported-docs`
|
|||
|
tool, it automatically clones the `kubernetes/kubernetes` repository.
|
|||
|
|
{{< /note >}}
|
|||
|
|
|
|||
|
|
## Editing the Kubernetes source code
|
|||
|
|
|
|||
|
|
The reference documentation for the Kubernetes components and tools is automatically
|
|||
|
|
generated from the Kubernetes source code. If you want to change the reference documentation,
|
|||
|
|
the first step is to change one or more comments in the Kubernetes source code. Make the
|
|||
|
|
change in your local kubernetes/kubernetes repository, and then submit a pull request to
|
|||
|
|
the master branch of
|
|||
|
|
[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes).
|
|||
|
|
|
|||
|
|
[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942)
|
|||
|
|
is an example of a pull request that makes changes to comments in the Kubernetes
|
|||
|
|
source code.
|
|||
|
|
|
|||
|
|
Monitor your pull request, and respond to reviewer comments. Continue to monitor
|
|||
|
|
your pull request until it is merged into the master branch of the
|
|||
|
|
`kubernetes/kubernetes` repository.
|
|||
|
|
|
|||
|
|
## Cherry picking your change into a release branch
|
|||
|
|
|
|||
|
|
Your change is now in the master branch, which is used for development of the next
|
|||
|
|
Kubernetes release. If you want your change to appear in the docs for a Kubernetes
|
|||
|
|
version that has already been released, you need to propose that your change be cherry
|
|||
|
|
picked into the release branch.
|
|||
|
|
|
|||
|
|
For example, suppose the master branch is being used to develop Kubernetes 1.10, and
|
|||
|
|
you want to backport your change to the release-1.9 branch. For instructions on how
|
|||
|
|
to do this, see
|
|||
|
|
[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md).
|
|||
|
|
|
|||
|
|
Monitor your cherry-pick pull request until it is merged into the release branch.
|
|||
|
|
|
|||
|
|
{{< note >}}
|
|||
|
|
**Note:** Proposing a cherry pick requires that you have permission to set a label
|
|||
|
|
and a 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 >}}
|
|||
|
|
|
|||
|
|
## Overview of update-imported-docs
|
|||
|
|
|
|||
|
|
The `update-imported-docs` tool performs these steps:
|
|||
|
|
|
|||
|
|
1. Clone the `kubernetes/kubernetes` repository.
|
|||
|
|
1. Run several scripts under `kubernetes/kubernetes/hack`. These scripts
|
|||
|
|
generate Markdown files and place the files under `kubernetes/kubernetes/docs`.
|
|||
|
|
1. Copy the generated Markdown files to a local clone of the `kubernetes/website`
|
|||
|
|
repository under `kubernetes/website/docs/reference/generated`.
|
|||
|
|
1. Clone the `kubernetes/federation` repository.
|
|||
|
|
1. Run several scripts under `kubernetes/federation/hack`. These scripts
|
|||
|
|
generate Markdown files and place the files under `kubernetes/federation/docs`.
|
|||
|
|
1. Copy the generated Markdown files to a local clone of the `kubernetes/website`
|
|||
|
|
repository under `kubernetes/website/docs/reference/generated`.
|
|||
|
|
|
|||
|
|
After the Markdown files are in your local clone of the `kubernetes/website`
|
|||
|
|
repository, you can submit them in a
|
|||
|
|
[pull request](https://kubernetes.io/docs/home/contribute/create-pull-request/)
|
|||
|
|
to `kubernetes/website`.
|
|||
|
|
|
|||
|
|
## Setting the branch
|
|||
|
|
|
|||
|
|
Open `<web-base>/update-imported-docs/config.yaml` for editing.
|
|||
|
|
|
|||
|
|
Set the value of `branch` to the Kubernetes release that you want to document.
|
|||
|
|
For example, if you want to generate docs for the Kubernetes 1.9 release,
|
|||
|
|
set `branch` to `release-1.9`.
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
repos:
|
|||
|
|
- name: kubernetes
|
|||
|
|
remote: https://github.com/kubernetes/kubernetes.git
|
|||
|
|
branch: release-1.9
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Setting sources and destinations
|
|||
|
|
|
|||
|
|
The `update-imported-docs` tool uses `src` and `dst` fields
|
|||
|
|
in `config.yaml` to know which files to copy from the `kubernetes/kubernetes`
|
|||
|
|
repository and where to place those files in the `kubernetes/website`
|
|||
|
|
repository.
|
|||
|
|
|
|||
|
|
For example, suppose you want the tool to copy the `kube-apiserver.md` file
|
|||
|
|
from the `docs/admin` directory of the `kubernetes/kubernetes` repository
|
|||
|
|
to the `docs/reference/generated/` directory of the `kubernetes/website`
|
|||
|
|
repository. Then you would include a `src` and `dst` in your `config.yaml`
|
|||
|
|
file like this:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
repos:
|
|||
|
|
- name: kubernetes
|
|||
|
|
remote: https://github.com/kubernetes/kubernetes.git
|
|||
|
|
branch: release-1.9
|
|||
|
|
files:
|
|||
|
|
- src: docs/admin/kube-apiserver.md
|
|||
|
|
dst: docs/reference/generated/kube-apiserver.md
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The configuration is similar for files in the `kubernetes/federation`
|
|||
|
|
repository. Here's an example that configures the tool to copy `kubefed_init.md`
|
|||
|
|
from the `docs/admin` directory of the `kubernetes/federation` repository
|
|||
|
|
to the `docs/reference/generated` directory of the `kubernetes/website` repository:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
- name: federation
|
|||
|
|
remote: https://github.com/kubernetes/federation.git
|
|||
|
|
# # Change this to a release branch when federation has release branches.
|
|||
|
|
branch: master
|
|||
|
|
files:
|
|||
|
|
- src: docs/admin/kubefed_init.md
|
|||
|
|
dst: docs/reference/generated/kubefed_init.md
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Here's an example a `config.yaml` file that shows the sources and
|
|||
|
|
destinations of all the Markdown files that were generated and copied
|
|||
|
|
by the `update-imported-docs` tool at the beginning of the Kubernetes
|
|||
|
|
1.9 release.
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
repos:
|
|||
|
|
- name: kubernetes
|
|||
|
|
remote: https://github.com/kubernetes/kubernetes.git
|
|||
|
|
branch: release-1.9
|
|||
|
|
files:
|
|||
|
|
- src: docs/admin/cloud-controller-manager.md
|
|||
|
|
dst: docs/reference/generated/cloud-controller-manager.md
|
|||
|
|
- src: docs/admin/kube-apiserver.md
|
|||
|
|
dst: docs/reference/generated/kube-apiserver.md
|
|||
|
|
- src: docs/admin/kube-controller-manager.md
|
|||
|
|
dst: docs/reference/generated/kube-controller-manager.md
|
|||
|
|
- src: docs/admin/kubelet.md
|
|||
|
|
dst: docs/reference/generated/kubelet.md
|
|||
|
|
- src: docs/admin/kube-proxy.md
|
|||
|
|
dst: docs/reference/generated/kube-proxy.md
|
|||
|
|
- src: docs/admin/kube-scheduler.md
|
|||
|
|
dst: docs/reference/generated/kube-scheduler.md
|
|||
|
|
- src: docs/user-guide/kubectl/kubectl.md
|
|||
|
|
dst: docs/reference/generated/kubectl/kubectl.md
|
|||
|
|
- name: federation
|
|||
|
|
remote: https://github.com/kubernetes/federation.git
|
|||
|
|
# # Change this to a release branch when federation has release branches.
|
|||
|
|
branch: master
|
|||
|
|
files:
|
|||
|
|
- src: docs/admin/federation-apiserver.md
|
|||
|
|
dst: docs/reference/generated/federation-apiserver.md
|
|||
|
|
- src: docs/admin/federation-controller-manager.md
|
|||
|
|
dst: docs/reference/generated/federation-controller-manager.md
|
|||
|
|
- src: docs/admin/kubefed_init.md
|
|||
|
|
dst: docs/reference/generated/kubefed_init.md
|
|||
|
|
- src: docs/admin/kubefed_join.md
|
|||
|
|
dst: docs/reference/generated/kubefed_join.md
|
|||
|
|
- src: docs/admin/kubefed.md
|
|||
|
|
dst: docs/reference/generated/kubefed.md
|
|||
|
|
- src: docs/admin/kubefed_options.md
|
|||
|
|
dst: docs/reference/generated/kubefed_options.md
|
|||
|
|
- src: docs/admin/kubefed_unjoin.md
|
|||
|
|
dst: docs/reference/generated/kubefed_unjoin.md
|
|||
|
|
- src: docs/admin/kubefed_version.md
|
|||
|
|
dst: docs/reference/generated/kubefed_version.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Running the update-imported-docs tool
|
|||
|
|
|
|||
|
|
Now that your `config.yaml` file contains your sources and destinations,
|
|||
|
|
you can run the `update-imported-docs` tool:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
cd <web-base>
|
|||
|
|
go get ./update-imported-docs
|
|||
|
|
go run update-imported-docs/update-imported-docs.go
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 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: docs/reference/generated/cloud-controller-manager.md
|
|||
|
|
modified: docs/reference/generated/federation-apiserver.md
|
|||
|
|
modified: docs/reference/generated/federation-controller-manager.md
|
|||
|
|
modified: docs/reference/generated/kube-apiserver.md
|
|||
|
|
modified: docs/reference/generated/kube-controller-manager.md
|
|||
|
|
modified: docs/reference/generated/kube-proxy.md
|
|||
|
|
modified: docs/reference/generated/kube-scheduler.md
|
|||
|
|
modified: docs/reference/generated/kubectl/kubectl.md
|
|||
|
|
modified: docs/reference/generated/kubefed.md
|
|||
|
|
modified: docs/reference/generated/kubefed_init.md
|
|||
|
|
modified: docs/reference/generated/kubefed_join.md
|
|||
|
|
modified: docs/reference/generated/kubefed_options.md
|
|||
|
|
modified: docs/reference/generated/kubefed_unjoin.md
|
|||
|
|
modified: docs/reference/generated/kubefed_version.md
|
|||
|
|
modified: docs/reference/generated/kubelet.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/).
|
|||
|
|
|
|||
|
|
{{% /capture %}}
|
|||
|
|
|
|||
|
|
{{% capture whatsnext %}}
|
|||
|
|
|
|||
|
|
* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
|
|||
|
|
* [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/)
|
|||
|
|
|
|||
|
|
{{% /capture %}}
|
|||
|
|
|
|||
|
|
|
|||
|
|
|