updating contrib for ref docs (kubernetes#18787)

more cleanup

Author: kbhawkey

content/en/docs/contribute/generate-ref-docs/_index.md

@@ -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/)

content/en/docs/contribute/generate-ref-docs/contribute-upstream.md

@@ -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 %}}
-

content/en/docs/contribute/generate-ref-docs/kubectl.md

@@ -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:
+For example:
 
-```
-WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
-K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
-MINOR_VERSION=15
+```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 a version directory
+## Creating a versioned 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.
+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>/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:
+In the `<rdocs-base>` directory, run the following build target:
 
 ```shell
-mkdir gen-kubectldocs/generators/v1_15
-cp -r gen-kubectldocs/generators/v1_14/* gen-kubectldocs/generators/v1_15
+cd <rdocs-base>
+make createversiondirs
 ```
 
-## Checking out a branch in k8s.io/kubernetes
+## Checking out a release tag in k8s.io/kubernetes
 
-In your local <k8s-base> repository, checkout the branch that has
+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 %}}