Qiming
ad80069302
* Revise guide for generating reference docs This PR changes the guidance for generating reference documentation for Kubernetes API and kubernetes components. The topic of making changes to the upstream repo is separated out because 1) it is not a mandatory step for generating the reference docs; 2) it is about a more advanced level of documentation fix. * light copyedit * more light copyedits
209 lines
7.3 KiB
Markdown
209 lines
7.3 KiB
Markdown
---
|
|
title: Generating Reference Documentation for the Kubernetes API
|
|
content_template: templates/task
|
|
---
|
|
|
|
{{% capture overview %}}
|
|
|
|
This page shows how to update the generated reference docs for the
|
|
Kubernetes API.
|
|
|
|
{{% /capture %}}
|
|
|
|
|
|
{{% capture prerequisites %}}
|
|
|
|
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
|
|
[Creating a Documentation Pull Request](/docs/contribute/start/) and
|
|
[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962).
|
|
|
|
{{% /capture %}}
|
|
|
|
|
|
{{% capture steps %}}
|
|
|
|
## The big picture
|
|
|
|
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).
|
|
|
|
If you find bugs in the generated documentation generated, 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
|
|
spec, continue reading this page.
|
|
|
|
## Getting three repositories
|
|
|
|
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>`.
|
|
|
|
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 don't already have the kubernetes-incubator/reference-docs repository, get it now:
|
|
|
|
```shell
|
|
mkdir $GOPATH/src
|
|
cd $GOPATH/src
|
|
go get github.com/kubernetes-incubator/reference-docs
|
|
```
|
|
|
|
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>`.
|
|
|
|
## Generating the API reference docs for publishing
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### Editing Makefile in kubernetes-incubator/reference-docs
|
|
|
|
Go to `<rdocs-base>`, and open `Makefile` for editing:
|
|
|
|
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`.
|
|
|
|
### 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:
|
|
|
|
```shell
|
|
make updateapispec
|
|
```
|
|
|
|
The output shows that the file was copied:
|
|
|
|
```shell
|
|
cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
|
|
```
|
|
|
|
### Building the API reference docs
|
|
|
|
Run the following command to generate the API reference docs:
|
|
|
|
```shell
|
|
cd <rdocs-base>
|
|
make api
|
|
```
|
|
|
|
### Locate the generated files
|
|
|
|
These two files are the output of a successful build. Verify that they exist:
|
|
|
|
* `<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
|
|
|
|
The preceding sections showed how to generate reference documentation for publication.
|
|
|
|
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" >}}/).
|
|
|
|
Enter the following command to copy the generated files to
|
|
your local kubernetes/website repository:
|
|
|
|
```shell
|
|
make copyapi
|
|
```
|
|
|
|
Go to the base of your local kubernetes/website repository, and
|
|
see which files have been modified:
|
|
|
|
```shell
|
|
cd <web-base>
|
|
git status
|
|
```
|
|
|
|
The output shows the modified files:
|
|
|
|
```shell
|
|
On branch master
|
|
...
|
|
modified: docs/reference/generated/kubernetes-api/v1.9/index.html
|
|
```
|
|
|
|
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.
|
|
|
|
In `<web-base>` run `git add` and `git commit` to commit the change.
|
|
|
|
Submit your changes as a
|
|
[pull request](/docs/contribute/start/) to the
|
|
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
|
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 %}}
|
|
|
|
* [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 Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
|
|
|
|
{{% /capture %}}
|
|
|