Skip to content

Commit

Permalink
Update api reference contrib doc
Browse files Browse the repository at this point in the history 
See issue kubernetes#14111
  • Loading branch information
@kbhawkey
kbhawkey committed Jun 26, 2019
1 parent 30fb1aa commit b71e73d
Showing 1 changed file with 110 additions and 95 deletions.
205 changes: 110 additions & 95 deletions content/en/docs/contribute/generate-ref-docs/kubernetes-api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,17 @@ content_template: templates/task

{{% capture overview %}}

This page shows how to update the generated reference docs for the
Kubernetes API.
This page shows how to update the generated reference docs for the Kubernetes API.
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-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs).


If you find bugs in the generated documentation, you need to
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).

If you need only to regenerate the reference documentation from the [OpenAPI](https://github.com/OAI/OpenAPI-Specification)
spec, continue reading this page.

{{% /capture %}}

Expand All @@ -18,8 +27,6 @@ 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

Your $GOPATH environment variable must be set.

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
Expand All @@ -31,96 +38,74 @@ information, see

{{% capture steps %}}

## The big picture
## Set up the local repositories

The reference documentation for the Kubernetes API is generated in two separate stages:

1. Generate an OpenAPI spec from the Kubernetes source code. The tools for
this stage are at [kubernetes/kubernetes/hack](https://github.com/kubernetes/kubernetes/tree/master/hack).

1. Generate an HTML file from the OpenAPI spec. The tools for this stage are at
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs).
```shell
export GOPATH=$HOME/<your-local-dir>

If you find bugs in the generated documentation generated, you need to
[fix them upstream](/docs/contribute/generate-ref-docs/contribute-upstream/).
go get -u github.com/kubernetes/website
go get -u github.com/kubernetes/kubernetes
go get -u github.com/kubernetes-incubator/reference-docs

If you need only to regenerate the reference documentation from the OpenAPI
spec, continue reading this page.
go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec
```

## Getting three repositories
The base directory of your clone of the
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is
`$GOPATH/src/github.com/kubernetes/kubernetes.`
The remaining steps refer to your base directory as `<k8s-base>`.

If you don't already have the kubernetes/kubernetes repository, get it now:
The base directory of your clone of the
[kubernetes/website](https://github.com/kubernetes/website) repository is
`$GOPATH/src/github.com/kubernetes/website.`
The remaining steps refer to your base directory as `<web-base>`.

```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes
```
The base directory of your clone of the
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs)
repository is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`.

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>`.

If you don't already have the kubernetes/website repository, get it now:
Clone your fork of the kubernetes/website or create a local branch in `<web-base>`
to submit the generated API reference files.

```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/website
git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/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 don't already have the kubernetes-incubator/reference-docs repository, get it now:
Or

```shell
mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs
cd <web-base>
git checkout -b <new-branch-name> upstream/master
```

Determine the base directory of your clone of the
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) repository.
For example, if you followed the preceding step to get the repository, your
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.`
The remaining steps refer to your base directory as `<rdocs-base>`.
## Generate the API reference docs

## Generating the API reference docs for publishing
This section shows how to generate the
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).

The preceding section showed how to edit a source file and then generate
several files, including `api/openapi-spec/swagger.json` in the
`kubernetes/kubernetes` repository.
### Modify the Makefile

This section shows how to generate the
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/),
which is generated by the tools at
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs).
Those tools take the `api/openapi-spec/swagger.json` file as input.
Go to `<rdocs-base>`, and open the `Makefile` for editing:

### Editing Makefile in kubernetes-incubator/reference-docs
* Set `K8SROOT` to the base directory of your local kubernetes/kubernetes
repository.
* Set `WEBROOT` to the base directory of your local kubernetes/website repository.
* 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.9, set `MINOR_VERSION` to 9. Save and close the `Makefile`.

Go to `<rdocs-base>`, and open `Makefile` for editing:
For example, update the following variables:

Set `K8SROOT` to the base directory of your local kubernetes/kubernetes
repository. Set `WEBROOT` to the base directory of your local kubernetes/website repository.
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.9, set `MINOR_VERSION` to 9. Save and close `Makefile`.
```bash
WEBROOT=$(GOPATH)/src/github.com/kubernetes/website
K8SROOT=$(GOPATH)/src/github.com/kubernetes/kubernetes
MINOR_VERSION=15
```

### Copying the OpenAPI spec

The doc generation code needs a local copy of the OpenAPI spec for the Kubernetes API.
Go to `<k8s-base>` and check out the branch that has the OpenAPI spec you want to use.
For example, if you want to generate docs for Kubernetes 1.9, checkout the release-1.9
branch.

Go back to `<rdocs-base>`. Enter the following command to copy the OpenAPI spec from the
`kubernetes/kubernetes` repository to a local directory:
Run the following command in `<rdocs-base>`:

```shell
make updateapispec
Expand All @@ -134,31 +119,29 @@ cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apid

### Building the API reference docs

Run the following command to generate the API reference docs:
Run the following command in `<rdocs-base>`:

```shell
cd <rdocs-base>
make api
```

### Locate the generated files
Verify that these two files have been generated:

These two files are the output of a successful build. Verify that they exist:
* [ -e "<rdocs-base>/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
* [ -e "<rdocs-base>/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

* `<rdocs-base>/gen-apidocs/generators/build/index.html`
* `<rdocs-base>/gen-apidocs/generators/build/navData.js`

## Copying the generated docs to the kubernetes/website repository
### Creating directories for published docs

The preceding sections showed how to generate reference documentation for publication.
```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
```

This section shows how to copy the generated reference to the
[kubernetes/website](https://github.com/kubernetes/website) repository. The files
in the `kubernetes/website` repository are published in the
[kubernetes.io](https://kubernetes.io) website. In particular, the generated
`index.html` file is published [here](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
## Copying the generated docs to the kubernetes/website repository

Enter the following command to copy the generated files to
Run the following command in `<rdocs-base>` to copy the generated files to
your local kubernetes/website repository:

```shell
Expand All @@ -176,14 +159,50 @@ git status
The output shows the modified files:

```shell
On branch master
...
modified: docs/reference/generated/kubernetes-api/v1.9/index.html
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
```

## Updating the API reference index pages


* Open `<web-base>/content/en/docs/reference/kubernetes-api/index.md` for editing, and update the API reference
version number. For example:

```
---
title: v1.15
---
[Kubernetes API v1.15](/docs/reference/generated/kubernetes-api/v1.15/)
```

* 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.


## Locally test the documentation

Build the Kubernetes documentation and verify the local preview.

```shell
cd <web-base>
make docker-serve
```

In this example, only one file has been modified. Recall that you generated both
`index.html` and `navData.js`. But apparently the generated `navata.js` is not different
from the `navData.js` that was already in the kubernetes/website` repository.
## Commit the changes

In `<web-base>` run `git add` and `git commit` to commit the change.

Expand All @@ -193,9 +212,6 @@ Submit your changes as a
Monitor your pull request, and respond to reviewer comments as needed. Continue
to monitor your pull request until it has been merged.

A few minutes after your pull request is merged, your changes will be visible
in the [published reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).

{{% /capture %}}

{{% capture whatsnext %}}
Expand All @@ -204,5 +220,4 @@ in the [published reference documentation](/docs/reference/generated/kubernetes-
* [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/)

{{% /capture %}}

{{% /capture %}}

0 comments on commit b71e73d

Please sign in to comment.