Skip to content

Commit

Permalink
updating contrib for ref docs (#18787)
Browse files Browse the repository at this point in the history 
more cleanup
  • Loading branch information
@kbhawkey
kbhawkey committed Feb 6, 2020
1 parent 79e1b94 commit 1210760
Show file tree
Hide file tree
Showing 8 changed files with 424 additions and 376 deletions.
11 changes: 7 additions & 4 deletions content/en/docs/contribute/generate-ref-docs/_index.md
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 18 additions & 22 deletions content/en/docs/contribute/generate-ref-docs/contribute-upstream.md
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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 %}}

101 changes: 39 additions & 62 deletions content/en/docs/contribute/generate-ref-docs/kubectl.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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 %}}
Loading

0 comments on commit 1210760

Please sign in to comment.