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 b594ea9dd4..4eff9594af 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,16 @@ 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 +26,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 +37,78 @@ information, see {{% capture steps %}} -## The big picture +## Setting 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). - -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: +Create a local workspace and set your `GOPATH`. ```shell -mkdir $GOPATH/src -cd $GOPATH/src -go get github.com/kubernetes/kubernetes +mkdir -p $HOME/ + +export GOPATH=$HOME/ ``` -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 ``. +Get a local clone of the following repositories: + +```shell +go get -u github.com/kubernetes-incubator/reference-docs + +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: ```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: +Get a clone of the kubernetes/kubernetes repository as k8s.io/kubernetes: ```shell -mkdir $GOPATH/src -cd $GOPATH/src -go get github.com/kubernetes-incubator/reference-docs +git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes ``` -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 base directory of your clone of the +[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository is +`$GOPATH/src/k8s.io/kubernetes.` +The remaining steps refer to your base directory as ``. + +* The base directory of your clone of the +[kubernetes/website](https://github.com/kubernetes/website) repository is +`$GOPATH/src/github.com//website.` +The remaining steps refer to your base directory as ``. + +* 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 ``. -## 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. +## Generating the API reference docs 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. +[published Kubernetes API reference documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/). -### Editing Makefile in kubernetes-incubator/reference-docs +### Modifying the Makefile -Go to ``, and open `Makefile` for editing: +Go to ``, and open the `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`. +* Set `K8SROOT` to ``. +* Set `WEBROOT` to ``. +* 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.15, set `MINOR_VERSION` to 15. Save and close the `Makefile`. + +For example, update the following variables: + +``` +WEBROOT=$(GOPATH)/src/github.com//website +K8SROOT=$(GOPATH)/src/k8s.io/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 @@ -129,43 +117,44 @@ 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 +cp ~/src/k8s.io/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: +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: +```shell +[ -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` +### Creating directories for published docs + +Create the directories in `` for the generated API reference files: + +```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 +``` ## 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 +Run the following command in `` 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 +Go to the base of your local kubernetes/website repository, and see which files have been modified: ```shell @@ -175,15 +164,52 @@ 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 ``` -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. +## 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 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 +make docker-serve +``` + +## Commit the changes In `` 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 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 +227,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