whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

updating contrib for ref docs (#18787)

Browse Source 
more cleanup
This commit is contained in:
Karen Bradshaw
2020-02-06 16:53:25 -05:00
committed by GitHub
parent 79e1b94c91
commit 121076085c
8 changed files with 433 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/generate-ref-docs/kubectl.md
+44 -67
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 %}}