whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update api reference contrib doc (#15114)

Browse Source 
* Update api reference contrib doc

See issue #14111

* updates to api ref contrib guide

* further updates to api ref contrib

* more updates api ref contrib
This commit is contained in:
Karen Bradshaw
2019-07-07 00:00:34 -04:00
committed by Kubernetes Prow Robot
parent 7db830ab61
commit 48e68a9eb5
1 changed files with 119 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/generate-ref-docs/kubernetes-api.md
+117 -95
View File
@@ -5,8 +5,16 @@ content_template: templates/task
{{% capture overview %}} {{% capture overview %}}
This page shows how to update the generated reference docs for the This page shows how to update the generated reference docs for the Kubernetes API.
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 %}} {{% /capture %}}
@@ -18,8 +26,6 @@ You need to have these tools installed:
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* [Golang](https://golang.org/doc/install) version 1.9.1 or later * [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. 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 Typically, this involves creating a fork of the repository. For more
information, see information, see
@@ -31,96 +37,78 @@ information, see
{{% capture steps %}} {{% capture steps %}}
## The big picture ## Setting up the local repositories
The reference documentation for the Kubernetes API is generated in two separate stages: Create a local workspace and set your `GOPATH`.
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 ```shell
mkdir $GOPATH/src mkdir -p $HOME/<workspace>
cd $GOPATH/src
go get github.com/kubernetes/kubernetes export GOPATH=$HOME/<workspace>
``` ```
Determine the base directory of your clone of the Get a local clone of the following repositories:
[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository.
For example, if you followed the preceding step to get the repository, your ```shell
base directory is `$GOPATH/src/github.com/kubernetes/kubernetes.` go get -u github.com/kubernetes-incubator/reference-docs
The remaining steps refer to your base directory as `<k8s-base>`.
go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec
```
If you don't already have the kubernetes/website repository, get it now: If you don't already have the kubernetes/website repository, get it now:
```shell ```shell
mkdir $GOPATH/src git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website
cd $GOPATH/src
go get github.com/kubernetes/website
``` ```
Determine the base directory of your clone of the Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes:
[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 ```shell
mkdir $GOPATH/src git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes
cd $GOPATH/src
go get github.com/kubernetes-incubator/reference-docs
``` ```
Determine the base directory of your clone of the * The base directory of your clone of the
[kubernetes-incubator/reference-docs](https://github.com/kubernetes-incubator/reference-docs) repository. [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is
For example, if you followed the preceding step to get the repository, your `$GOPATH/src/k8s.io/kubernetes.`
base directory is `$GOPATH/src/github.com/kubernetes-incubator/reference-docs.` The remaining steps refer to your base directory as `<k8s-base>`.
* The base directory of your clone of the
[kubernetes/website](https://github.com/kubernetes/website) repository is
`$GOPATH/src/github.com/<your username>/website.`
The remaining steps refer to your base directory as `<web-base>`.
* 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>`. 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 ## Generating the API reference docs
several files, including `api/openapi-spec/swagger.json` in the
`kubernetes/kubernetes` repository.
This section shows how to generate the This section shows how to generate the
[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/), [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 ### Modifying the Makefile
Go to `<rdocs-base>`, and open `Makefile` for editing: Go to `<rdocs-base>`, and open the `Makefile` for editing:
Set `K8SROOT` to the base directory of your local kubernetes/kubernetes * Set `K8SROOT` to `<k8s-base>`.
repository. Set `WEBROOT` to the base directory of your local kubernetes/website repository. * Set `WEBROOT` to `<web-base>`.
Set `MINOR_VERSION` to the minor version of the docs you want to build. For example, * 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`. if you want to build docs for Kubernetes 1.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`.
For example, update the following variables:
```
WEBROOT=$(GOPATH)/src/github.com/<your-username>/website
K8SROOT=$(GOPATH)/src/k8s.io/kubernetes
MINOR_VERSION=15
```
### Copying the OpenAPI spec ### Copying the OpenAPI spec
The doc generation code needs a local copy of the OpenAPI spec for the Kubernetes API. Run the following command in `<rdocs-base>`:
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 ```shell
make updateapispec make updateapispec
@@ -129,36 +117,37 @@ make updateapispec
The output shows that the file was copied: The output shows that the file was copied:
```shell ```shell
cp ~/src/github.com/kubernetes/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json cp ~/src/k8s.io/kubernetes/api/openapi-spec/swagger.json gen-apidocs/generators/openapi-spec/swagger.json
``` ```
### Building the API reference docs ### Building the API reference docs
Run the following command to generate the API reference docs: Run the following command in `<rdocs-base>`:
```shell ```shell
cd <rdocs-base>
make api 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: ```shell
[ -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` ### Creating directories for published docs
* `<rdocs-base>/gen-apidocs/generators/build/navData.js`
Create the directories in `<web-base>` for the generated API reference files:
```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
```
## Copying the generated docs to the kubernetes/website repository ## Copying the generated docs to the kubernetes/website repository
The preceding sections showed how to generate reference documentation for publication. Run the following command in `<rdocs-base>` to copy the generated files to
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: your local kubernetes/website repository:
```shell ```shell
@@ -175,15 +164,52 @@ git status
The output shows the modified files: The output shows the modified files:
```shell ```
On branch master 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
modified: docs/reference/generated/kubernetes-api/v1.9/index.html 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
``` ```
In this example, only one file has been modified. Recall that you generated both ## Updating the API reference index pages
`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.
* 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 API reference
Publish a local version of the API reference.
Verify the [local preview](http://localhost:1313/docs/reference/generated/kubernetes-api/v1.15/).
```shell
cd <web-base>
make docker-serve
```
## Commit the changes
In `<web-base>` run `git add` and `git commit` to commit the change. In `<web-base>` run `git add` and `git commit` to commit the change.
@@ -193,9 +219,6 @@ Submit your changes as a
Monitor your pull request, and respond to reviewer comments as needed. Continue Monitor your pull request, and respond to reviewer comments as needed. Continue
to monitor your pull request until it has been merged. 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 %}}
{{% capture whatsnext %}} {{% capture whatsnext %}}
@@ -205,4 +228,3 @@ in the [published reference documentation](/docs/reference/generated/kubernetes-
* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/) * [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
{{% /capture %}} {{% /capture %}}