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

Revise guide for generating reference docs (#13375)

Browse Source 
* Revise guide for generating reference docs

This PR changes the guidance for generating reference documentation for
Kubernetes API and kubernetes components. The topic of making changes to
the upstream repo is separated out because 1) it is not a mandatory step
for generating the reference docs; 2) it is about a more advanced level
of documentation fix.

* light copyedit

* more light copyedits
This commit is contained in:
Qiming
2019-04-20 03:45:54 +08:00
committed by Kubernetes Prow Robot
parent e61a551566
commit ad80069302
3 changed files with 272 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/contribute/generate-ref-docs/kubernetes-components.md
+8 -46
View File
@@ -19,19 +19,15 @@ reference documentation for tools and components in the
* 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/).
information, see [Creating a Documentation Pull Request](/docs/contribute/start/).
{{% /capture %}}
@@ -68,49 +64,16 @@ 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>`.
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,
please follow [this guide](/docs/contribute/gen-ref-docs/contribute-upstream).
{{< 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 `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 is located in the `kubernetes/website/update-imported-docs/`
@@ -125,8 +88,7 @@ directory. The tool performs the following steps:
repository under locations specified in the configuration file.
When the Markdown files are in your local clone of the `kubernetes/website`
repository, you can submit them in a
[pull request](/docs/home/contribute/create-pull-request/)
repository, you can submit them in a [pull request](/docs/contribute/start/)
to `kubernetes/website`.
## Customizing the config file
@@ -237,5 +199,5 @@ topics will be visible in the
* [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/)
{{% /capture %}}
* [Contributing to the Upstream Kubernetes Project for Documentation](/docs/contribute/gen-ref-docs/contribute-upstream)
{{% /capture %}}