diff --git a/_data/docs-home.yml b/_data/docs-home.yml index ee3b471e3d1fd..3a795cbbc2fbb 100644 --- a/_data/docs-home.yml +++ b/_data/docs-home.yml @@ -20,3 +20,10 @@ toc: - docs/home/contribute/review-issues.md - docs/home/contribute/style-guide.md - docs/home/contribute/includes.md + + - title: Updating Automatically Generated Reference Pages + section: + - docs/home/contribute/generated-reference/kubernetes-components.md + - docs/home/contribute/generated-reference/kubectl.md + - docs/home/contribute/generated-reference/kubernetes-api.md + - docs/home/contribute/generated-reference/federation-api.md diff --git a/_data/glossary/persistent-volume-claim.yaml b/_data/glossary/persistent-volume-claim.yaml index 6929a7516a1af..8e7fe41ab7b3b 100644 --- a/_data/glossary/persistent-volume-claim.yaml +++ b/_data/glossary/persistent-volume-claim.yaml @@ -10,6 +10,6 @@ tags: - core-object - storage short-description: > - Claims storage resources defined in a {% glossary_tooltip text="PersistentVolume (PV)" term_id="persistent-volume" %} so that it can be mounted as a volume in a container. + Claims storage resources defined in a PersistentVolume so that it can be mounted as a volume in a container. long-description: | Specifies the amount of storage, how the storage will be accessed (read-only, read-write and/or exclusive) and how it is reclaimed (retained, recycled or deleted). Details of the storage itself are in the PersistentVolume specification. diff --git a/docs/home/contribute/generated-reference/federation-api.md b/docs/home/contribute/generated-reference/federation-api.md new file mode 100644 index 0000000000000..6a22a664e7d1e --- /dev/null +++ b/docs/home/contribute/generated-reference/federation-api.md @@ -0,0 +1,91 @@ +--- +title: Generating Reference Documentation for Kubernetes Federation API +--- + +{% capture overview %} + +This page shows how to automatically generate reference pages for the +Kubernetes Federation API. + +{% endcapture %} + + +{% capture prerequisites %} + +* You need to have +[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +installed. + +* You need to have +[Golang](https://golang.org/doc/install) version 1.8 or later installed, +and your `$GOPATH` environment variable must be set. + +* You need to have +[Docker](https://docs.docker.com/engine/installation/) installed. + +* You need to know how to create a pull request to a GitHub repository. +Typically, this involves creating a fork of the repository. For more +information, see +[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/). + +{% endcapture %} + + +{% capture steps %} + +## Running the update-federation-api-docs.sh script + +If you don't already have the Kubernetes federation source code, get it now: + +```shell +mkdir $GOPATH/src +cd $GOPATH/src +go get github.com/kubernetes/federation +``` + +Determine the base directory of your local +[kubernetes/federation](https://github.com/kubernetes/federation) repository. +For example, if you followed the preceding step to get the federation source +code, you base directory is `$GOPATH/src/github.com/kubernetes/federation.` +The remaining steps refer to your base directory as ``. + +Run the doc generation script: + +```shell +cd +hack/update-federation-api-reference-docs.sh +``` + +The script runs the +[gcr.io/google_containers/gen-swagger-docs](https://console.cloud.google.com/gcr/images/google-containers/GLOBAL/gen-swagger-docs?gcrImageListquery=%255B%255D&gcrImageListpage=%257B%2522t%2522%253A%2522%2522%252C%2522i%2522%253A0%257D&gcrImageListsize=50&gcrImageListsort=%255B%257B%2522p%2522%253A%2522uploaded%2522%252C%2522s%2522%253Afalse%257D%255D) +image to generate this set of reference docs: + +* /docs/api-reference/extensions/v1beta1/operations.html +* /docs/api-reference/extensions/v1beta1/definitions.html +* /docs/api-reference/v1/operations.html +* /docs/api-reference/v1/definitions.html + +The generated files do not get published automatically. They have to be manually copied to the +[kubernetes/website](https://github.com/kubernetes/website/tree/master/docs/reference/generated) +repository. + +These files are published at +[kubernetes.io/docs/reference](/docs/reference/): + +* [Federation API v1 Operations](https://kubernetes.io/docs/reference/federation/v1/operations/) +* [Federation API v1 Definitions](https://kubernetes.io/docs/reference/federation/v1/definitions/) +* [Federation API extensions/v1beta1 Operations](https://kubernetes.io/docs/reference/federation/extensions/v1beta1/operations/) +* [Federation API extensions/v1beta1 Definitions](https://kubernetes.io/docs/reference/federation/extensions/v1beta1/definitions/) + +{% endcapture %} + +{% capture whatsnext %} + +* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/) +* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/) +* [Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/) + +{% endcapture %} + + +{% include templates/task.md %} diff --git a/docs/home/contribute/generated-reference/kubectl.md b/docs/home/contribute/generated-reference/kubectl.md new file mode 100644 index 0000000000000..225240d77eaea --- /dev/null +++ b/docs/home/contribute/generated-reference/kubectl.md @@ -0,0 +1,262 @@ +--- +title: Generating Reference Documentation for kubectl Commands +--- + +{% capture overview %} + +This page shows how to automatically generate reference pages for the +commands provided by the `kubectl` tool. + +**Note:** +This topic shows how to generate reference documentation for +[kubectl commands](/docs/reference/generated/kubectl/kubectl-commands) +like +[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands#apply) and +[kubectl taint](/docs/reference/generated/kubectl/kubectl-commands#taint). +This topic does not show how to generate the +[kubectl](/docs/reference/generated/kubectl/kubectl/) +options reference page. For instructions on how to generate the kubectl options +reference page, see +[Generating Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/). +{: .note} + +{% endcapture %} + + +{% capture prerequisites %} + +* You need to have +[Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +installed. + +* You need to have +[Golang](https://golang.org/doc/install) version 1.8 or later installed, +and your `$GOPATH` environment variable must be set. + +* You need to have +[Docker](https://docs.docker.com/engine/installation/) installed. + +* You need to know how to create a pull request to a GitHub repository. +Typically, this involves creating a fork of the repository. For more +information, see +[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/) and +[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962). + +{% endcapture %} + + +{% capture steps %} + +## 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 ``. + +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 ``. + +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 ``. + +In your local kubernetes/kubernetes repository, check out the branch of interest, +and make sure it is up to date. For example, if you want to generate docs for +Kubernetes 1.9, you could use these commands: + +```shell +cd +git checkout release-1.9 +git pull https://github.com/kubernetes/kubernetes release-1.9 +``` + +## Editing the kubectl source code + +The reference documentation for the kubectl commands is automatically generated from +kubectl source code. If you want to change the reference documentation, the first step +is to change one or more comments in the kubectl source code. Make the change in your +local kubernetes/kubernetes repository, and then submit a pull request to the master branch of +[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). + +[PR 56673](https://github.com/kubernetes/kubernetes/pull/56673/files) +is an example of a pull request that fixes a typo in the kubectl source code. + +Monitor your pull request, and respond to reviewer comments. Continue to monitor your +pull request until it is merged into the master branch of the kubernetes/kubernetes repository. + +## Cherry picking your change into a release branch + +Your change is now in the master branch, which is used for development of the next +Kubernetes release. If you want your change to appear in the docs for a Kubernetes +version that has already been released, you need to propose that your change be +cherry picked into the release branch. + +For example, suppose the master branch is being used to develop Kubernetes 1.10, +and you want to backport your change to the release-1.9 branch. For instructions +on how to do this, see +[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md). + +Monitor your cherry-pick pull request until it is merged into the release branch. + +**Note:** +Proposing a cherry pick requires that you have permission to set a label and a +milestone in your pull request. If you don’t have those permissions, you will +need to work with someone who can set the label and milestone for you. +{: .note} + +## Editing Makefile + +Go to ``, 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`. + +## Building the brodocs image + +The doc generation code requires the `pwittrock/brodocs` Docker image. + +This command creates the `pwittrock/brodocs` Docker image. It also tries to push the image to +DockerHub, but it's OK if that step fails. As long as you have the image locally, the code generation +can succeed. + + +```shell +make brodocs +``` + +Verify that you have the brodocs image: + +```shell +docker images +``` + +The output shows `pwittrock/brodocs` as one of the available images: + +```shell +REPOSITORY TAG IMAGE ID CREATED SIZE +pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB +``` + +## Creating a version directory + +In the `gen-kubectldocs/generators` directory, if you do not already +have a directory named `v1_MINOR_VERSION`, create one now by copying the directory +for the previous version. For example, suppose you want to generate docs for +Kubernetes 1.9, but you don't already have a `v1_9` directory. Then you could +create and populate a `v1_9` directory by running these commands: + +```shell +mkdir gen-kubectldocs/generators/v1_9 +cp -r gen-kubectldocs/generators/v1_8/* gen-kubectldocs/generators/v1_9 +``` + +## Checking out a branch in kubernetes/kubernetes + +In you local kubernetes/kubernetes repository, checkout the branch that has +the version of Kubernetes that you want to document. For example, if you want +to generate docs for Kubernetes 1.9, checkout the release-1.9 branch. Make sure +you local branch is up to date. + +## Running the doc generation code + +In you local kubernetes-incubator/reference-docs repository, build and run the +doc generation code. You might need to run the command as root: + +```shell +cd +make cli +``` + +## Locate the generated files + +These two files are the primary output of a successful build. Verify that they exist: + +* `/gen-kubectldocs/generators/build/index.html` +* `/gen-kubectldocs/generators/build/navData.js` + +## Copying files to the kubernetes/website repository + +Copy the generated files from your local kubernetes-incubator/reference-docs +repository to your local kubernetes/website repository. + +```shell +cd +make copycli +``` + +## Adding and committing changes in kubernetes/website + +List the files that were generated and copied to the `kubernetes/website` +repository: + +``` +cd +git status +``` + +The output shows the new and modified files. For example, the output +might look like this: + +```shell +modified: docs/reference/generated/kubectl/kubectl-commands.html +modified: docs/reference/generated/kubectl/navData.js +``` + +Run `git add` and `git commit` to commit the files. + +## Creating a pull request + +Create a pull request to the `kubernetes/website` repository. Monitor your +pull request, and respond to review comments as needed. Continue to monitor +your pull request until it is merged. + +A few minutes after your pull request is merged, your updated reference +topics will be visible in the +[published documentation](/docs/home). + + +{% endcapture %} + +{% capture whatsnext %} + +* [Generating Reference Documentation for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/) +* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/) +* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/) + +{% endcapture %} + + +{% include templates/task.md %} diff --git a/docs/home/contribute/generated-reference/kubernetes-api.md b/docs/home/contribute/generated-reference/kubernetes-api.md new file mode 100644 index 0000000000000..1dddd6f946b99 --- /dev/null +++ b/docs/home/contribute/generated-reference/kubernetes-api.md @@ -0,0 +1,376 @@ +--- +title: Generating Reference Documentation for the Kubernetes API +--- + +{% capture overview %} + +This page shows how to update the automatically generated reference docs for the +Kubernetes API. + +{% endcapture %} + + +{% 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.8 or later +* [Docker](https://docs.docker.com/engine/installation/) +* [etcd](https://github.com/coreos/etcd/) + +Your $GOPATH environment variable must be set, and the location of `etcd` +must be in your $PATH environment variable. + +You need to know how to create a pull request to a GitHub repository. +Typically, this involves creating a fork of the repository. For more +information, see +[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/) and +[GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962). + +{% endcapture %} + + +{% capture steps %} + +## The big picture + +Updating the Kubernetes API reference documentation is a two-stage process: + +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/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). + +## 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 ``. + +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 ``. + +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 ``. + +## Editing the Kubernetes source code + +The Kubernetes API reference documentation is automatically generated from +an OpenAPI spec, which is generated from the Kubernetes source code. If you +want to change the reference documentation, the first step is to change one +or more comments in the Kubernetes source code. + +### Making changes to comments in the source code + +**Note**: The following steps are an example, not a general procedure. Details +will be different in your situation. +{: .note} + +Here's an example of editing the a comment in the Kubernetes source code. + +In your local kubernetes/kubernetes repository, check out the master branch, +and make sure it is up to date: + +```shell +cd +git checkout master +git pull https://github.com/kubernetes/kubernetes master +``` + +Suppose this source file in the master branch has the typo "atmost": + +[kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go](https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/api/apps/v1/types.go) + +In your local environment, open `types.go`, and change "atmost" to "at most". + +Verify that you have changed the file: + +```shell +git status +``` + +The output shows that you are on the master branch, and that the `types.go` +source file has been modified: + +```shell +On branch master +... + modified: staging/src/k8s.io/api/apps/v1/types.go +``` + +### Committing your edited file + +Run `git add` and `git commit` to commit the changes you have made so far. In the next step, +you will do a second commit. It is important to keep your changes separated into two commits. + +### Generating the OpenAPI spec and related files + +Go to `` and run these scripts: + +```shell +hack/update-generated-swagger-docs.sh +hack/update-swagger-spec.sh +hack/update-openapi-spec.sh +hack/update-generated-protobuf.sh +hack/update-api-reference-docs.sh +``` + +Run `git status` to see what was generated. + +```shell +On branch master +... + modified: api/openapi-spec/swagger.json + modified: api/swagger-spec/apps_v1.json + modified: docs/api-reference/apps/v1/definitions.html + modified: staging/src/k8s.io/api/apps/v1/generated.proto + modified: staging/src/k8s.io/api/apps/v1/types.go + modified: staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go +``` + +View the contents of `api/openapi-spec/swagger.json` to make sure the typo is fixed. +For example, you could run `git diff -a api/openapi-spec/swagger.json`. +This is important, because `swagger.json` will be the input to the second stage of +the doc generation process. + +Run `git add` and `git commit` to commit your changes. Now you have two commits: +one that has the edited `types.go` file, and one that has the generated OpenAPI spec +and related files. Keep these two commits separate. That is, do not squash your commits. + +Submit your changes as a +[pull request](https://help.github.com/articles/creating-a-pull-request/) to the +master branch of the +[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repository. +Monitor your pull request, and respond to reviewer comments as needed. Continue +to monitor your pull request until it has been merged. + +[PR 57758](https://github.com/kubernetes/kubernetes/pull/57758) +is an example of a pull request that fixes a typo in the Kubernetes source code. + +**Note**: It can be tricky to determine the correct source file to be changed. In the +preceding example, the authoritative source file is under the `staging` directory +in the `kubernetes/kubernetes` repository. But in your situation,the `staging` directory +might not be the place to find the authoritative source. For guidance, check the +`README` files in +[kubernetes/kubernetes](https://github.com/kubernetes/kubernetes/tree/master/staging) +repository and in related repositories like +[kubernetes/apiserver](https://github.com/kubernetes/apiserver/blob/master/README.md). +{: .note} + +### Cherry picking your commit into a release branch + +In the preceding section, you edited a file in the master branch and then ran scripts +to generate an OpenAPI spec and related files. Then you submitted your changes in a pull request +to the master branch of the kubernetes/kubernetes repository. Now suppose you want to backport +your change into a release branch. For example, suppose the master branch is being used to develop +Kubernetes version 1.10, and you want to backport your change into the release-1.9 branch. + +Recall that your pull request has two commits: one for editing `types.go` +and one for the files generated by scripts. The next step is to propose a cherry pick of your first +commit into the release-1.9 branch. The idea is to cherry pick the commit that edited `types.go`, but not +the commit that has the results of running the scripts. For instructions, see +[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md). + +**Note:** Proposing a cherry pick requires that you have permission to set a label and a milestone in your +pull request. If you don't have those permissions, you will need to work with someone who can set the label +and milestone for you. + +When you have a pull request in place for cherry picking your one commit into the release-1.9 branch, +the next step is to run these scripts in the release-1.9 branch of your local environment. + +```shell +hack/update-generated-swagger-docs.sh +hack/update-swagger-spec.sh +hack/update-openapi-spec.sh +hack/update-generated-protobuf.sh +hack/update-api-reference-docs.sh +``` + +Now add a commit to your cherry-pick pull request that has the recently generated OpenAPI spec +and related files. Monitor your pull request until it gets merged into the release-1.9 branch. + +At this point, both the master branch and the release-1.9 branch have your updated `types.go` +file and a set of generated files that reflect the change you made to `types.go`. Note that the +generated OpenAPI spec and other generated files in the release-1.9 branch are not necessarily +the same as the generated files in the master branch. The generated files in the release-1.9 branch +contain API elements only from Kubernetes 1.9. The generated files in the master branch might contain +API elements that are not in 1.9, but are under development for 1.10. + +## Generating the published reference docs + +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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/), +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 ``, 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 `` 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: + +```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 brodocs image + +The doc generation code requires the +[pwittrock/brodocs](https://github.com/pwittrock/brodocs) Docker image. + +This command creates the `pwittrock/brodocs` Docker image. It also tries to push the image to +DockerHub, but it's OK if that step fails. As long as you have the image locally, the code generation +can succeed. + +```shell +make brodocs +``` + +Verify that you have the brodocs image: + +```shell +docker images +``` + +The output shows `pwittrock/brodocs` as one of the available images: + +```shell +REPOSITORY TAG IMAGE ID CREATED SIZE +pwittrock/brodocs latest 999d34a50d56 5 weeks ago 714MB +``` + +### Running the doc generation code + +Build and run the doc generation code. You might need to run the command as root: + +```shell +cd +make api +``` + +### Locate the generated files + +These two files are the output of a successful build. Verify that they exist: + +* `/gen-apidocs/generators/build/index.html` +* `/gen-apidocs/generators/build/navData.js` + +## Copying the generated docs to the kubernetes/website repository + +The preceding sections showed how to edit a Kubernetes source file, +generate an OpenAPI spec, and then generate reference documentation for publication. + +This section show how to copy the generated docs 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.9/). + +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/kubernetes repository, and +see which files have been modified: + +```shell +cd +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 `` run `git add` and `git commit` to commit the change. + +Submit your changes as a +[pull request](/docs/home/contribute/create-pull-request/) 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/v1.9/). + +{% endcapture %} + +{% 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/) + +{% endcapture %} + + +{% include templates/task.md %} diff --git a/docs/home/contribute/generated-reference/kubernetes-components.md b/docs/home/contribute/generated-reference/kubernetes-components.md new file mode 100644 index 0000000000000..375fb38b4c965 --- /dev/null +++ b/docs/home/contribute/generated-reference/kubernetes-components.md @@ -0,0 +1,303 @@ +--- +title: Generating Reference Pages for Kubernetes Components and Tools +--- + +{% capture overview %} + +This page shows how to use the `update-imported-docs` tool to generate +reference documentation for tools and components in the +[Kubernetes](https://github.com/kubernetes/kubernetes) and +[Federation](https://github.com/kubernetes/federation) repositories. + +{% endcapture %} + + +{% capture prerequisites %} + +* You need a machine that is running Linux or MacOS. + +* You need to have this software installed: + + * [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + + * [Golang](https://golang.org/doc/install) version 1.9 or later + + * [make](https://www.gnu.org/software/make/) + + * [gcc compiler/linker](https://gcc.gnu.org/) + +* Your `$GOPATH` environment variable must be set. + +* You need to know how to create a pull request to a GitHub repository. +Typically, this involves creating a fork of the repository. For more +information, see +[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/). + +{% endcapture %} + + +{% capture steps %} + +## Getting two repositories + +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 ``. + +If you plan on making changes to the ref docs, and 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 ``. + +**Note:** +If you only need to generate, but not change, the reference docs, you don't need to +manually get the `kubernetes/kubernetes` repository. When you run the `update-imported-docs` +tool, it automatically clones the the `kubernetes/kubernetes` repository. +{: .note} + +## Editing the Kubernetes source code + +The reference documentation for the Kubernetes components and tools is automatically +generated from the Kubernetes source code. If you want to change the reference documentation, +the first step is to change one or more comments in the Kubernetes source code. Make the +change in your local kubernetes/kubernetes repository, and then submit a pull request to +the master branch of +[github.com/kubernetes/kubernetes](https://github.com/kubernetes/kubernetes). + +[PR 56942](https://github.com/kubernetes/kubernetes/pull/56942) +is an example of a pull request that makes changes to comments in the Kubernetes +source code. + +Monitor your pull request, and respond to reviewer comments. Continue to monitor +your pull request until it is merged into the master branch of the +`kubernetes/kubernetes` repository. + +## Cherry picking your change into a release branch + +Your change is now in the master branch, which is used for development of the next +Kubernetes release. If you want your change to appear in the docs for a Kubernetes +version that has already been released, you need to propose that your change be cherry +picked into the release branch. + +For example, suppose the master branch is being used to develop Kubernetes 1.10, and +you want to backport your change to the release-1.9 branch. For instructions on how +to do this, see +[Propose a Cherry Pick](https://github.com/kubernetes/community/blob/master/contributors/devel/cherry-picks.md). + +Monitor your cherry-pick pull request until it is merged into the release branch. + +**Note:** Proposing a cherry pick requires that you have permission to set a label +and a milestone in your pull request. If you don’t have those permissions, you will +need to work with someone who can set the label and milestone for you. +{: .note} + +## Overview of update-imported-docs + +The `update-imported-docs` tool performs these steps: + +1. Clone the `kubernetes/kubernetes` repository. +1. Run several scripts under `kubernetes/kubernetes/hack`. These scripts + generate Markdown files and place the files under `kubernetes/kubernetes/docs`. +1. Copy the generated Markdown files to a local clone of the `kubernetes/website` + repository under `kubernetes/website/docs/reference/generated`. +1. Clone the `kubernetes/federation` repository. +1. Run several scripts under `kubernetes/federation/hack`. These scripts + generate Markdown files and place the files under `kubernetes/federation/docs`. +1. Copy the generated Markdown files to a local clone of the `kubernetes/website` + repository under `kubernetes/website/docs/reference/generated`. + +After the Markdown files are in your local clone of the `kubernetes/website` +repository, you can submit them in a +[pull request](https://kubernetes.io/docs/home/contribute/create-pull-request/) +to `kubernetes/website`. + +## Setting the branch + +Open `/update-imported-docs/config.yaml` for editing. + +Set the value of `branch` to the Kubernetes release that you want to document. +For example, if you want to generate docs for the Kubernetes 1.9 release, +set `branch` to `release-1.9`. + +```shell +repos: +- name: kubernetes + remote: https://github.com/kubernetes/kubernetes.git + branch: release-1.9 +``` + +## Setting sources and destinations + +The `update-imported-docs` tool uses `src` and `dst` fields +in `config.yaml` to know which files to copy from the `kubernetes/kubernetes` +repository and where to place those files in the `kubernetes/website` +repository. + +For example, suppose you want the tool to copy the `kube-apiserver.md` file +from the `docs/admin` directory of the `kubernetes/kubernetes` repository +to the `docs/reference/generated/` directory of the `kubernetes/website` +repository. Then you would include a `src` and `dst` in your `config.yaml` +file like this: + +```shell +repos: +- name: kubernetes + remote: https://github.com/kubernetes/kubernetes.git + branch: release-1.9 + files: + - src: docs/admin/kube-apiserver.md + dst: docs/reference/generated/kube-apiserver.md + ... +``` + +The configuration is similar for files in the `kubernetes/federation` +repository. Here's an example that configures the tool to copy `kubefed_init.md` +from the `docs/admin` directory of the `kubernetes/federation` repository +to the `docs/reference/generated` directory of the `kubernetes/website` repository: + +```shell +- name: federation + remote: https://github.com/kubernetes/federation.git +# # Change this to a release branch when federation has release branches. + branch: master + files: + - src: docs/admin/kubefed_init.md + dst: docs/reference/generated/kubefed_init.md + ... +``` + +Here's an example a `config.yaml` file that shows the sources and +destinations of all the Markdown files that were generated and copied +by the `update-imported-docs` tool at the beginning of the Kubernetes +1.9 release. + +```shell +repos: +- name: kubernetes + remote: https://github.com/kubernetes/kubernetes.git + branch: release-1.9 + files: + - src: docs/admin/cloud-controller-manager.md + dst: docs/reference/generated/cloud-controller-manager.md + - src: docs/admin/kube-apiserver.md + dst: docs/reference/generated/kube-apiserver.md + - src: docs/admin/kube-controller-manager.md + dst: docs/reference/generated/kube-controller-manager.md + - src: docs/admin/kubelet.md + dst: docs/reference/generated/kubelet.md + - src: docs/admin/kube-proxy.md + dst: docs/reference/generated/kube-proxy.md + - src: docs/admin/kube-scheduler.md + dst: docs/reference/generated/kube-scheduler.md + - src: docs/user-guide/kubectl/kubectl.md + dst: docs/reference/generated/kubectl/kubectl.md +- name: federation + remote: https://github.com/kubernetes/federation.git +# # Change this to a release branch when federation has release branches. + branch: master + files: + - src: docs/admin/federation-apiserver.md + dst: docs/reference/generated/federation-apiserver.md + - src: docs/admin/federation-controller-manager.md + dst: docs/reference/generated/federation-controller-manager.md + - src: docs/admin/kubefed_init.md + dst: docs/reference/generated/kubefed_init.md + - src: docs/admin/kubefed_join.md + dst: docs/reference/generated/kubefed_join.md + - src: docs/admin/kubefed.md + dst: docs/reference/generated/kubefed.md + - src: docs/admin/kubefed_options.md + dst: docs/reference/generated/kubefed_options.md + - src: docs/admin/kubefed_unjoin.md + dst: docs/reference/generated/kubefed_unjoin.md + - src: docs/admin/kubefed_version.md + dst: docs/reference/generated/kubefed_version.md + ``` + +## Running the update-imported-docs tool + +Now that your `config.yaml` file contains your sources and destinations, +you can run the `update-imported-docs` tool: + +```shell +cd +go get ./update-imported-docs +go run update-imported-docs/update-imported-docs.go +``` + +## Adding and committing changes in kubernetes/website + +List the files that were generated and copied to the `kubernetes/website` +repository: + +``` +cd +git status +``` + +The output shows the new and modified files. For example, the output +might look like this: + +```shell +... + modified: docs/reference/generated/cloud-controller-manager.md + modified: docs/reference/generated/federation-apiserver.md + modified: docs/reference/generated/federation-controller-manager.md + modified: docs/reference/generated/kube-apiserver.md + modified: docs/reference/generated/kube-controller-manager.md + modified: docs/reference/generated/kube-proxy.md + modified: docs/reference/generated/kube-scheduler.md + modified: docs/reference/generated/kubectl/kubectl.md + modified: docs/reference/generated/kubefed.md + modified: docs/reference/generated/kubefed_init.md + modified: docs/reference/generated/kubefed_join.md + modified: docs/reference/generated/kubefed_options.md + modified: docs/reference/generated/kubefed_unjoin.md + modified: docs/reference/generated/kubefed_version.md + modified: docs/reference/generated/kubelet.md +``` + +Run `git add` and `git commit` to commit the files. + +## Creating a pull request + +Create a pull request to the `kubernetes/website` repository. Monitor your +pull request, and respond to review comments as needed. Continue to monitor +your pull request until it is merged. + +A few minutes after your pull request is merged, your updated reference +topics will be visible in the +[published documentation](/docs/home/). + +{% endcapture %} + +{% capture whatsnext %} + +* [Generating Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/) +* [Generating Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/) +* [Generating Reference Documentation for the Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/) + +{% endcapture %} + + +{% include templates/task.md %}