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