From b71e73d3a2717f5f34c8e2f5efe2ea21492ef25e Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Tue, 25 Jun 2019 19:02:30 -0400 Subject: [PATCH] Update api reference contrib doc See issue #14111 --- .../generate-ref-docs/kubernetes-api.md | 205 ++++++++++-------- 1 file changed, 110 insertions(+), 95 deletions(-) diff --git a/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md b/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md index b594ea9dd4693..dfa4c7162e35a 100644 --- a/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md +++ b/content/en/docs/contribute/generate-ref-docs/kubernetes-api.md @@ -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 %}} @@ -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 @@ -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/ -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 ``. -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 ``. -```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 ``. -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 ``. -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 `` +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//website $GOPATH/src/github.com//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 ``. - -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 +git checkout -b 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 ``. +## 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 ``, 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 ``, 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 `` 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 ``. Enter the following command to copy the OpenAPI spec from the -`kubernetes/kubernetes` repository to a local directory: +Run the following command in ``: ```shell make updateapispec @@ -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 ``: ```shell -cd 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 "/gen-apidocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html" +* [ -e "/gen-apidocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js" -* `/gen-apidocs/generators/build/index.html` -* `/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 /static/docs/reference/generated/kubernetes-api/v1. +mkdir -p /static/docs/reference/generated/kubernetes-api/v1./css +mkdir -p /static/docs/reference/generated/kubernetes-api/v1./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 `` to copy the generated files to your local kubernetes/website repository: ```shell @@ -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 `/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 `/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 +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 `` run `git add` and `git commit` to commit the change. @@ -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 %}} @@ -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 %}} \ No newline at end of file