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

Reorganize docs contrib guide (#9510)

Browse Source 
* Reorganize docs contrib guide

* Address first round of feedback from Brad, Jared

* Standardize on 'SIG Docs'

* Address more feedback

* Rewrites to participating.md

* Tweak navigation titles

* Document PR Wrangler

* Document SIG Docs chairperson

* Fix codeblock that shows how to use <codenew>

It was being interpreted as a Hugo shortcode.
This commit is contained in:
Misty Linville
2018-08-06 16:15:57 -07:00
committed by k8s-ci-robot
parent 4920a51665
commit 5ae0d0dd8d
38 changed files with 1891 additions and 860 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/en/docs/home/contribute/_index.md
-5
View File
@@ -1,5 +0,0 @@
---
title: "Contributing to the Kubernetes Docs"
weight: 40
---
content/en/docs/home/contribute/blog-post.md
-134
View File
@@ -1,134 +0,0 @@
---
title: Writing a Blog Post
reviewers:
- zacharysarah
- kbarnard10
- sarahkconway
content_template: templates/task
---
{{% capture overview %}}
This page shows you how to submit a post for the [Kubernetes Blog](https://kubernetes.io/blog).
You’ll receive a response within 5 business days on whether your submission is approved and information about next steps, if any.
{{% /capture %}}
{{% capture prerequisites %}}
To create a new blog post, you can either:
- Fill out the [Kubernetes Blog Submission](https://docs.google.com/forms/d/e/1FAIpQLSch_phFYMTYlrTDuYziURP6nLMijoXx_f7sLABEU5gWBtxJHQ/viewform) form.
or:
- Open a pull request against this repository as described in
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/)
{{% /capture %}}
{{% capture steps %}}
## Kubernetes Blog guidelines
All content must be original. The Kubernetes Blog does not post material previously published elsewhere.
Suitable Content (with examples):
- User case studies (Yahoo Japan, Bitmovin)
- New Kubernetes capabilities (5-days-of-k8s)
- Kubernetes projects updates (kompose)
- Updates from Special Interest Groups (SIG-OpenStack)
- Tutorials and walkthroughs (PostgreSQL w/ StatefulSets)
- Thought leadership around Kubernetes (CaaS, the foundation for next generation PaaS)
- Kubernetes Partner OSS integration (Fission)
Unsuitable Content:
- Vendor product pitches
- Partner updates without an integration and customer story
- Syndicated posts (language translations are permitted)
## Create a blog post with a form
Open the [Kubernetes Blog Submission](https://docs.google.com/forms/d/e/1FAIpQLSch_phFYMTYlrTDuYziURP6nLMijoXx_f7sLABEU5gWBtxJHQ/viewform) form, fill it out, and click Submit.
## Create a post by opening a pull request
### Add a new Markdown file
Add a new Markdown (`*.md`) to `/blog/_posts/`.
Name the file using the following format:
```
YYYY-MM-DD-Title.md
```
For example:
```
2015-03-20-Welcome-to-the-Kubernetes-Blog.md
```
### Add front matter to the file
Add the following block to the top of the new file:
```
---
layout: blog
title: <title>
date: <date>
---
```
For example:
```
---
layout: blog
title: Welcome to the Kubernetes Blog!
date: Saturday, March 20, 2015
---
```
### Create a new pull request (PR)
When you [create a new pull request](/docs/home/contribute/create-pull-request/), include the following in the PR description:
{{< note >}}
- Desired publishing date
**Note:** PRs must include complete drafts no later than 15 days prior to the desired publication date.
{{< /note >}}
- Author information:
- Name
- Title
- Company
- Contact email
### Add content to the file
Write your post using the following guidelines.
### Add images
Add any image files the post contains to `/static/images/blog/`.
The preferred image format is SVG.
Add the proposed date of your blog post to the title of any image files the post contains:
```
YYYY-MM-DD-image.svg
```
For example:
```
2018-03-01-cncf-color.svg
```
Please use [reference-style image links][ref-style] to keep posts readable.
Here's an example of how to include an image in a blog post:
```
Check out the ![CNCF logo][cncf-logo].
[cncf-logo]: /images/blog/2018-03-01-cncf-color.svg
```
{{% /capture %}}
[ref-style]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#images
content/en/docs/home/contribute/content-organization.md
-142
View File
@@ -1,142 +0,0 @@
---
title: Content Organization
date: 2018-04-30
content_template: templates/concept
weight: 42
---
{{< toc >}}
{{% capture overview %}}
This site uses Hugo. In Hugo, [content organization](https://gohugo.io/content-management/organization/) is a core concept.
{{% /capture %}}
{{% capture body %}}
{{% note %}}
**Hugo Tip:** Start Hugo with `hugo server --navigateToChanged` for content edit-sessions.
{{% /note %}}
## Page Lists
### Page Order
The documentation side menu, the documentation page browser etc. are listed using Hugo's default sort order, which sorts by weight (from 1), date (newest first) and finally by the link title.
Given that, if you want to move a page or a section up, set a weight in the page's front matter:
```yaml
title: My Page
weight: 10
```
{{% note %}}
For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later.
{{% /note %}}
### Documentation Main Menu
The `Documentation` main menu is built from the sections below `docs/` with the `main_menu` flag set in front matter of the `_index.md` section content file:
```yaml
main_menu: true
```
Note that the link title is fetched from the page's `linkTitle`, so if you want it to be something different than the title, change it in the content file:
```yaml
main_menu: true
title: Page Title
linkTitle: Title used in links
```
{{% note %}}
The above needs to be done per language. If you don't see your section in the menu, it is probably because it is not identified as a section by Hugo. Create a `_index.md` content file in the section folder.
{{% /note %}}
### Documentation Side Menu
The documentation side-bar menu is built from the _current section tree_ starting below `docs/`.
It will show all sections and their pages.
If you want a section or page to not be listed, set the `toc_hide` flag in front matter:
```yaml
toc_hide: true
```
When you navigate to a section, the page shown is the section page (e.g. `_index.md`) if it has content, else the first page inside that section.
### Documentation Browser
The page browser on the documentation home page is built from all sections and pages directly below the `docs section`.
If you want a section or page to not be listed, set the `toc_hide` flag in front matter:
```yaml
toc_hide: true
```
### The Main Menu
The site links in the top-right menu -- and also in the footer -- are built by page-lookups. This is to make sure that the page actually exists. So, if the `case-studies` section does not exist in a site (language), it will not be linked to.
## Page Bundles
In addition to standalone content pages (Markdown files), Hugo supports [Page Bundles](https://gohugo.io/content-management/page-bundles/).
One example is [Custom Hugo Shortcodes](/docs/home/contribute/includes/). It is a socalled `leaf bundle`. Everything below the directory with the `index.md` will be part of the bundle, with page-relative links, images can be processed etc.:
```bash
en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json
```
Another example used widely is the `includes` bundle. It has `headless: true` set in front matter, which means that it does not get its own URL. It is only used in other pages.
```bash
en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── federation-content-moved.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md
```
Some important notes to the files in the bundles:
* For translated bundles, any missing non-content files will be inherited from languages above. This avoids duplication.
* All the files in a bundle are what Hugo calls `Resources` and you can provide metadata per language, such as parameters and title, even if it does not supports front matter (YAML files etc.). See [Page Resources Metadata](https://gohugo.io/content-management/page-resources/#page-resources-metadata).
* The value you get from `.RelPermalink` from a `Resource` is page-relative.
## Styles
The `SASS` source of the stylesheets for this site is stored below `src/sass` and can be built with `make sass` (note that Hugo will get `SASS` support soon, see https://github.com/gohugoio/hugo/issues/4243).
{{% /capture %}}
{{% capture whatsnext %}}
* [Custom Hugo Shortcodes](/docs/home/contribute/includes)
* [Style Guide](/docs/home/contribute/style-guide)
{{% /capture %}}
content/en/docs/home/contribute/create-pull-request.md
-122
View File
@@ -1,122 +0,0 @@
---
title: Creating a Documentation Pull Request
content_template: templates/task
---
{{% capture overview %}}
To contribute to the Kubernetes documentation, create a pull request against the
<a href="https://github.com/kubernetes/website" target="_blank" class="_">kubernetes/website</a>
repository. This page shows how to create a pull request.
{{% /capture %}}
{{% capture prerequisites %}}
1. Create a <a href="https://github.com/" target="_blank" class="_">Github account</a>.
1. Sign the
<a href="https://identity.linuxfoundation.org/projects/cncf" target="_blank" class="_">Linux Foundation Contributor License Agreement (CLA)</a>.
Documentation will be published under the [CC BY SA 4.0](https://git.k8s.io/website/LICENSE) license.
{{% /capture %}}
{{% capture steps %}}
## Creating a fork of the Kubernetes documentation repository
1. Go to the
<a href="https://github.com/kubernetes/website" target="_blank" class="_">kubernetes/website</a>
repository.
1. In the upper-right corner, click **Fork**. This creates a copy of the
Kubernetes documentation repository in your GitHub account. The copy
is called a *fork*.
## Making your changes
1. In your GitHub account, in your fork of the Kubernetes docs, create
a new branch to use for your contribution.
1. In your new branch, make your changes and commit them. If you want to
[write a new topic](/docs/home/contribute/write-new-topic/),
choose the
[page type](/docs/home/contribute/page-templates/)
that is the best fit for your content.
## Viewing your changes locally
You can use Hugo to see a preview of your changes locally.
1. [Install Hugo](https://gohugo.io/getting-started/installing/)
version 0.40.3 or later.
1. Go to the root directory of your clone of the Kubernetes docs, and
enter this command:
hugo server
1. In your browser's address bar, enter `localhost:1313`.
## Viewing your changes in the Netlify preview
When you submit a pull request, you can see a preview of your changes at
[Netlify](https://www.netlify.com/). In your pull request, at the bottom,
to the right of **deploy/netlify**, click **Details**. Also, there is often
a link to the Netlify preview in the pull request comments.
## Submitting a pull request to the master branch (Current Release)
If you want your change to be published in the released version Kubernetes docs,
create a pull request against the master branch of the Kubernetes
documentation repository.
1. In your GitHub account, in your new branch, create a pull request
against the master branch of the kubernetes/website
repository. This opens a page that shows the status of your pull request.
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
To the right of **deploy/netlify**, click **Details**. This opens a staging
site where you can verify that your changes have rendered correctly.
1. During the next few days, check your pull request for reviewer comments.
If needed, revise your pull request by committing changes to your
new branch in your fork.
## Submitting a pull request to the &lt;vnext&gt; branch (Upcoming Release)
If your documentation change should not be released until the next release of
the Kubernetes product, create a pull request against the &lt;vnext&gt; branch
of the Kubernetes documentation repository. The &lt;vnext&gt; branch has the
form `release-<version-number>`, for example release-1.5.
1. In your GitHub account, in your new branch, create a pull request
against the &lt;vnext&gt; branch of the kubernetes/website
repository. This opens a page that shows the status of your pull request.
1. Click **Show all checks**. Wait for the **deploy/netlify** check to complete.
To the right of **deploy/netlify**, click **Details**. This opens a staging
site where you can verify that your changes have rendered correctly.
1. During the next few days, check your pull request for reviewer comments.
If needed, revise your pull request by committing changes to your
new branch in your fork.
The staging site for the upcoming Kubernetes release is here:
[http://kubernetes-io-vnext-staging.netlify.com/](http://kubernetes-io-vnext-staging.netlify.com/).
The staging site reflects the current state of what's been merged in the
release branch, or in other words, what the docs will look like for the
next upcoming release. It's automatically updated as new PRs get merged.
## Pull request review process for both Current and Upcoming Releases
Once your pull request is created, a Kubernetes reviewer will take responsibility for providing clear, actionable feedback. As the owner of the pull request, **it is your responsibility to modify your pull request to address the feedback that has been provided to you by the Kubernetes reviewer.** Also note that you may end up having more than one Kubernetes reviewer provide you feedback or you may end up getting feedback from a Kubernetes reviewer that is different than the one originally assigned to provide you feedback. Furthermore, in some cases, one of your reviewers might ask for a technical review from a [Kubernetes tech reviewer](https://github.com/kubernetes/website/wiki/Tech-reviewers) when needed. Reviewers will do their best to provide feedback in a timely fashion but response time can vary based on circumstances.
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
{{% /capture %}}
content/en/docs/home/contribute/generated-reference/federation-api.md
-92
View File
@@ -1,92 +0,0 @@
---
title: Generating Reference Documentation for Kubernetes Federation API
content_template: templates/task
---
{{% capture overview %}}
This page shows how to automatically generate reference pages for the
Kubernetes Federation API.
{{% /capture %}}
{{% 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.9.1 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/).
{{% /capture %}}
{{% 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 `<fed-base>`.
Run the doc generation script:
```shell
cd <fed-base>
hack/update-federation-api-reference-docs.sh
```
The script runs the
[k8s.gcr.io/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/content/en/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/)
{{% /capture %}}
{{% 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/)
{{% /capture %}}
content/en/docs/home/contribute/generated-reference/kubectl.md
-265
View File
@@ -1,265 +0,0 @@
---
title: Generating Reference Documentation for kubectl Commands
content_template: templates/task
---
{{% capture overview %}}
This page shows how to automatically generate reference pages for the
commands provided by the `kubectl` tool.
{{< note >}}
**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 >}}
{{% /capture %}}
{{% 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.9.1 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).
{{% /capture %}}
{{% 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 `<k8s-base>`.
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 `<web-base>`.
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 `<rdocs-base>`.
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 <k8s-base>
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 >}}
**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 `<rdocs-base>`, 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 <rdocs-base>
make cli
```
## Locate the generated files
These two files are the primary output of a successful build. Verify that they exist:
* `<rdocs-base>/gen-kubectldocs/generators/build/index.html`
* `<rdocs-base>/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 <rdocs-base>
make copycli
```
## Adding and committing changes in kubernetes/website
List the files that were generated and copied to the `kubernetes/website`
repository:
```
cd <web-base>
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).
{{% /capture %}}
{{% 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/)
{{% /capture %}}
content/en/docs/home/contribute/generated-reference/kubernetes-api.md
-379
View File
@@ -1,379 +0,0 @@
---
title: Generating Reference Documentation for the Kubernetes API
content_template: templates/task
---
{{% capture overview %}}
This page shows how to update the automatically generated reference docs for the
Kubernetes API.
{{% /capture %}}
{{% 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.9.1 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).
{{% /capture %}}
{{% 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/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).
## 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 `<k8s-base>`.
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 `<web-base>`.
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 `<rdocs-base>`.
## 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 >}}
**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 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 <k8s-base>
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 `<k8s-base>` 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 >}}
**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](/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
Go to `<rdocs-base>`, 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 `<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
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 <rdocs-base>
make api
```
### Locate the generated files
These two files are the output of a successful build. Verify that they exist:
* `<rdocs-base>/gen-apidocs/generators/build/index.html`
* `<rdocs-base>/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](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
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 <web-base>
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 `<web-base>` 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/{{< param "version" >}}/).
{{% /capture %}}
{{% 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/)
{{% /capture %}}
content/en/docs/home/contribute/generated-reference/kubernetes-components.md
-306
View File
@@ -1,306 +0,0 @@
---
title: Generating Reference Pages for Kubernetes Components and Tools
content_template: templates/task
---
{{% 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.
{{% /capture %}}
{{% 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/).
{{% /capture %}}
{{% 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 `<web-base>`.
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 `<k8s-base>`.
{{< note >}}
**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 >}}
**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 `<web-base>/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 <web-base>
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 <web-base>
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/).
{{% /capture %}}
{{% 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/)
{{% /capture %}}
content/en/docs/home/contribute/includes/example1.md
-9
View File
@@ -1,9 +0,0 @@
---
title: Example #1
---
This is an **example** content file inside the **includes** leaf bundle.
{{< note >}}
**Note:** Included content files can also contain shortcodes.
{{< /note >}}
content/en/docs/home/contribute/includes/example2.md
-7
View File
@@ -1,7 +0,0 @@
---
title: Example #1
---
This is another **example** content file inside the **includes** leaf bundle.
content/en/docs/home/contribute/includes/index.md
-211
View File
@@ -1,211 +0,0 @@
---
approvers:
- chenopis
title: Custom Hugo Shortcodes
content_template: templates/concept
---
{{% capture overview %}}
This page explains the custom Hugo shortcodes that can be used in Kubernetes documentation markdown.
Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes).
{{% /capture %}}
{{% capture body %}}
## Feature state
In a markdown page (.md file) on this site, you can add a shortcode to display version and state of the documented feature.
### Feature state demo
Below is a demo of the feature state snippet. Here it is used to display the feature as stable in Kubernetes version 1.10.
```
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
```
Will render to:
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
The valid values for `state` are:
* alpha
* beta
* deprecated
* stable
### Feature state code
Below is the template code for each available feature state.
The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the <code>for_k8s_version</code> shortcode parameter.
````
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
````
Renders to:
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
#### Alpha feature
````
{{</* feature-state feature-state state="alpha" */>}}
````
Renders to:
{{< feature-state state="alpha" >}}
#### Beta feature
````
{{</* feature-state feature-state state="beta" */>}}
````
Renders to:
{{< feature-state state="beta" >}}
#### Stable feature
````
{{</* feature-state feature-state state="stable" */>}}
````
Renders to:
{{< feature-state state="stable" >}}
#### Deprecated feature
````
{{</* feature-state feature-state state="deprecated" */>}}
````
Renders to:
{{< feature-state state="deprecated" >}}
## Glossary
You can reference glossary terms with an inclusion that will automatically update and replace content with the relevant links from [our glossary](/docs/reference/glossary/). When the term is moused-over by someone
using the online documentation, the glossary entry will display a tooltip.
The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary), with a content file for each glossary term.
### Glossary Demo
For example, the following include within the markdown will render to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
````liquid
{{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
````
## Tabs
In a markdown page (`.md` file) on this site, you can add a tab set to display multiple flavors of a given solution.
The `tabs` shortcode takes these parameters:
* `name`: The name as shown on the tab.
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- will be looked up in the bundle itself. If not, the content page to include will be looked up relative to the current. Note that with the `include` you will not have any shortcode inner content and must use the self-closing syntax, e.g. {{</* tab name="Content File #1" include="example1" /*/>}}. Non-content files will be code-highlighted. The language to use will be taken from the filename if not provided in `codelang`.
* If your inner content is markdown, you must use `%`-delimiter to surorund the tab, e.g. `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
* You can combine the variations mentioned above inside a tab set.
Below is a demo of the tabs shortcode.
{{< note >}}
The tab **name** in a `tabs` definition must be unique within a content page.
{{< /note >}}
### Tabs demo: Code highlighting
```go-text-template
{{</* tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}}
{{< /tabs */>}}
```
Will be rendered as:
{{< tabs name="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}
### Tabs demo: Inline Markdown and HTML
```go-html-template
{{</* tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
<h3>Plain HTML</h3>
<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs */>}}
```
Will be rendered as:
{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}**Note:** It can even contain shortcodes.{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
<h3>Plain HTML</h3>
<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}
### Tabs demo: File include
```go-text-template
{{</* tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs */>}}
```
Will be rendered as:
{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [Hugo](https://gohugo.io/).
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
content/en/docs/home/contribute/includes/podtemplate.json
-22
View File
@@ -1,22 +0,0 @@
{
"apiVersion": "v1",
"kind": "PodTemplate",
"metadata": {
"name": "nginx"
},
"template": {
"metadata": {
"labels": {
"name": "nginx"
},
"generateName": "nginx-"
},
"spec": {
"containers": [{
"name": "nginx",
"image": "dockerfile/nginx",
"ports": [{"containerPort": 80}]
}]
}
}
}
content/en/docs/home/contribute/localization.md
-149
View File
@@ -1,149 +0,0 @@
---
title: Localizing Kubernetes Documentation
content_template: templates/concept
approvers:
- chenopis
- zacharysarah
---
{{% capture overview %}}
The Kubernetes documentation is currently available in [multiple languages](#supported-languages) and we encourage you to add new localizations ([l10n](https://blog.mozilla.org/l10n/2011/12/14/i18n-vs-l10n-whats-the-diff/))!
Currently available languages:
{{< language-repos-list >}}
In order for localizations to be accepted, however, they must fulfill some requirements related to workflow (*how* to localize) and output (*what* to localize).
{{% /capture %}}
{{< toc >}}
{{% capture body %}}
## Workflow
The Kubernetes documentation for all languages is built from the [kubernetes/website](https://github.com/kubernetes/website) repository on GitHub. Most day-to-work work on translations, however, happens in separate translation repositories. Changes to those repositories are then [periodically](#upstream-contributions) synced to the main kubernetes/website repository via [pull request](../create-pull-request).
Work on the Chinese translation, for example, happens in the [kubernetes/kubernetes-docs-zh](https://github.com/kubernetes/kubernetes-docs-zh) repository.
{{< note >}}
**Note**: For an example localization-related [pull request](../create-pull-request), see [this pull request](https://github.com/kubernetes/website/pull/8636) to the [Kubernetes website repo](https://github.com/kubernetes/website) adding Korean localization to the Kubernetes docs.
{{< /note >}}
## Source Files
Localizations must use English files from the most recent major release as sources. To find the most recent release's documentation source files:
1. Navigate to the Kubernetes website repository at https://github.com/kubernetes/website.
2. Select the `release-1.X` branch for the most recent version, which is currently **{{< latest-version >}}**, making the most recent release branch [`{{< release-branch >}}`](https://github.com/kubernetes/website/tree/{{< release-branch >}}).
## Getting started
In order to add a new localization of the Kubernetes documentation, you'll need to make a few modifications to the site's [configuration](#configuration) and [directory structure](#new-directory), and then you can get to work [translating documents](#translating-documents)!
To get started, clone the website repo and `cd` into it:
```shell
git clone https://github.com/kubernetes/website
cd website
git checkout {{< release-branch >}}
```
## Configuration
We'll walk you through the configuration process using the German language (language code `de`) as an example.
There's currently no translation for German, but you're welcome to create one using the instructions here.
The Kubernetes website's configuration is in the [`config.toml`](https://github.com/kubernetes/website/tree/master/config.toml) file. You need to add a configuration block for the new language to that file, under the existing `[languages]` block. The German block, for example, looks like this:
```toml
[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch"
contentDir = "content/de"
weight = 3
```
When assigning a `weight` parameter, see which of the current languages has the highest weight and add 1 to that value.
Now add a language-specific subdirectory to the [`content`](https://github.com/kubernetes/website/tree/master/content) folder. The two-letter code for German is `de`, so add a `content/de` directory:
```shell
mkdir content/de
```
## Translating documents
We understand that localizing *all* of the Kubernetes documentation would be an enormous task. We're okay with localizations smarting small and expanding over time.
As an initial requirement, all localizations must include the following documentation at a minimum:
Description | URLs
-----|-----
Home | [All heading and subheading URLs](https://kubernetes.io/docs/home/)
Setup | [All heading and subheading URLs](https://kubernetes.io/docs/setup/)
Tutorials | [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/), [Hello Minikube](https://kubernetes.io/docs/tutorials/stateless-application/hello-minikube/)
Translated documents should have the same URL endpoint as the English docs (substituting the subdirectory of the `content` folder). To translate the [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/) doc into German, for example, create the proper subfolder under the `content/de` folder and copy the English doc:
```shell
mkdir -p content/de/docs/tutorials
cp content/en/docs/tutorials/kubernetes-basics.md content/de/docs/tutorials/kubernetes-basics.md
```
## Project logistics
### Contact with project chairs
When starting a new localization effort, you should get in touch with one of the chairs of the Kubernetes [SIG Docs](https://github.com/kubernetes/community/tree/master/sig-docs) organization. The current chairs are listed [here](https://github.com/kubernetes/community/tree/master/sig-docs#chairs).
### Project information
Teams working on localization efforts must provide a single point of contact, including the name and contact information of a person who can respond to or redirect questions or concerns, listed in the translation repository's main [`README`](https://help.github.com/articles/about-readmes/). You can provide an email address, email list, [Slack channel](https://slack.com/), or some other method of contact.
### Maintainers
Each localization repository must select its own maintainers. Maintainers can be from a single organization or multiple organizations.
In addition, all l10n work must be self-sustaining with the team's own resources.
Wherever possible, every localized page must be approved by a reviewer from a different company than the translator.
### GitHub project
Each Kubernetes localization repository must track its overall progress with a [GitHub project](https://help.github.com/articles/creating-a-project-board/).
Projects must include at least these columns:
- To Do
- In Progress
- Done
{{< note >}}
**Note**: For an example GitHub project, see the [Chinese localization project](https://github.com/kubernetes/kubernetes-docs-zh/projects/1).
{{< /note >}}
### Repository structure
Each l10n repository must have branches for the different Kubernetes documentation release versions, matching the branches in the main [kubernetes/website](https://github.com/kubernetes/website) documentation repository. For example, the kubernetes/website `release-1.10` branch (https://github.com/kubernetes/website/tree/release-1.10) has a corresponding branch in the kubernetes/kubernetes-docs-zh repository (https://github.com/kubernetes/kubernetes-docs-zh/tree/release-1.10). These version branches keep track of the differences in the documentation between Kubernetes versions.
### Upstream contributions
Upstream contributions are welcome and encouraged!
For the sake of efficiency, limit upstream contributions to a single pull request per week, containing a single [squashed commit](https://github.com/todotxt/todo.txt-android/wiki/Squash-All-Commits-Related-to-a-Single-Issue-into-a-Single-Commit).
{{% /capture %}}
{{% capture whatsnext %}}
Once a l10n meets requirements for workflow and minimum output, SIG docs will:
- Work with the localization team to implement language selection on the website.
- Publicize availability through [Cloud Native Computing Foundation](https://www.cncf.io/) (CNCF) channels.
{{% /capture %}}
content/en/docs/home/contribute/page-templates.md
-231
View File
@@ -1,231 +0,0 @@
---
title: Using Page Templates
---
<!--<html>
<body>-->
<p>These page templates are available for writers who would like to contribute new topics to the Kubernetes docs:</p>
<ul>
<li><a href="#task_template">Task</a></li>
<li><a href="#tutorial_template">Tutorial</a></li>
<li><a href="#concept_template">Concept</a></li>
</ul>
<p>The page templates are in the <a href="https://git.k8s.io/website/_includes/templates" target="_blank">_includes/templates</a> directory of the <a href="https://github.com/kubernetes/website">website</a> repository.
<h2 id="task_template">Task template</h2>
<p>A task page shows how to do a single thing, typically by giving a short
sequence of steps. Task pages have minimal explanation, but often provide links
to conceptual topics that provide related background and knowledge.</p>
<p>To write a new task page, create a Markdown file in a subdirectory of the
/docs/tasks directory. In your Markdown file, provide values for these
variables:</p>
<ul>
<li>overview - required</li>
<li>prerequisites - required</li>
<li>steps - required</li>
<li>discussion - optional</li>
<li>whatsnext - optional</li>
</ul>
<p>Then include templates/task.md like this:</p>
{% raw %}<pre>...
{% include templates/task.md %}</pre>{% endraw %}
<p>In the <code>steps</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
use <code>###</code> and <code>####</code> as needed. Similarly, if you choose to have a <code>discussion</code> section,
start the section with a level-two heading.</p>
<p>Here's an example of a Markdown file that uses the task template:</p>
{% raw %}
<pre>---
title: Configuring This Thing
---
{% capture overview %}
This page shows how to ...
{% endcapture %}
{% capture prerequisites %}
* Do this.
* Do this too.
{% endcapture %}
{% capture steps %}
## Doing ...
1. Do this.
1. Do this next. Possibly read this [related explanation](...).
{% endcapture %}
{% capture discussion %}
## Understanding ...
Here's an interesting thing to know about the steps you just did.
{% endcapture %}
{% capture whatsnext %}
* Learn more about [this](...).
* See this [related task](...).
{% endcapture %}
{% include templates/task.md %}</pre>
{% endraw %}
<p>Here's an example of a published topic that uses the task template:</p>
<p><a href="/docs/tasks/access-kubernetes-api/http-proxy-access-api">Using an HTTP Proxy to Access the Kubernetes API</a></p>
<h2 id="tutorial_template">Tutorial template</h2>
<p>A tutorial page shows how to accomplish a goal that is larger than a single
task. Typically a tutorial page has several sections, each of which has a
sequence of steps. For example, a tutorial might provide a walkthrough of a
code sample that illustrates a certain feature of Kubernetes. Tutorials can
include surface-level explanations, but should link to related concept topics
for deep explanations.
<p>To write a new tutorial page, create a Markdown file in a subdirectory of the
/docs/tutorials directory. In your Markdown file, provide values for these
variables:</p>
<ul>
<li>overview - required</li>
<li>prerequisites - required</li>
<li>objectives - required</li>
<li>lessoncontent - required</li>
<li>cleanup - optional</li>
<li>whatsnext - optional</li>
</ul>
<p>Then include templates/tutorial.md like this:</p>
{% raw %}<pre>...
{% include templates/tutorial.md %}</pre>{% endraw %}
<p>In the <code>lessoncontent</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
use <code>###</code> and <code>####</code> as needed.
<p>Here's an example of a Markdown file that uses the tutorial template:</p>
{% raw %}
<pre>---
title: Running a Thing
---
{% capture overview %}
This page shows how to ...
{% endcapture %}
{% capture prerequisites %}
* Do this.
* Do this too.
{% endcapture %}
{% capture objectives %}
* Learn this.
* Build this.
* Run this.
{% endcapture %}
{% capture lessoncontent %}
## Building ...
1. Do this.
1. Do this next. Possibly read this [related explanation](...).
## Running ...
1. Do this.
1. Do this next.
## Understanding the code
Here's something interesting about the code you ran in the preceding steps.
{% endcapture %}
{% capture cleanup %}
* Delete this.
* Stop this.
{% endcapture %}
{% capture whatsnext %}
* Learn more about [this](...).
* See this [related tutorial](...).
{% endcapture %}
{% include templates/tutorial.md %}</pre>
{% endraw %}
<p>Here's an example of a published topic that uses the tutorial template:</p>
<p><a href="/docs/tutorials/stateless-application/run-stateless-application-deployment/">Running a Stateless Application Using a Deployment</a></p>
<h2 id="concept_template">Concept template</h2>
<p>A concept page explains some aspect of Kubernetes. For example, a concept
page might describe the Kubernetes Deployment object and explain the role it
plays as an application is deployed, scaled, and updated. Typically, concept
pages don't include sequences of steps, but instead provide links to tasks or
tutorials.
<p>To write a new concept page, create a Markdown file in a subdirectory of the
/docs/concepts directory. In your Markdown file, provide values for these
variables:</p>
<ul>
<li>overview - required</li>
<li>body - required</li>
<li>whatsnext - optional</li>
</ul>
<p>Then include templates/concept.md like this:</p>
{% raw %}<pre>...
{% include templates/concept.md %}</pre>{% endraw %}
<p>In the <code>body</code> section, use <code>##</code> to start with a level-two heading. For subheadings,
use <code>###</code> and <code>####</code> as needed.
<p>Here's an example of a page that uses the concept template:</p>
{% raw %}
<pre>---
title: Understanding this Thing
---
{% capture overview %}
This page explains ...
{% endcapture %}
{% capture body %}
## Understanding ...
Kubernetes provides ...
## Using ...
To use ...
{% endcapture %}
{% capture whatsnext %}
* Learn more about [this](...).
* See this [related task](...).
{% endcapture %}
{% include templates/concept.md %}</pre>
{% endraw %}
<p>Here's an example of a published topic that uses the concept template:</p>
<p><a href="/docs/concepts/overview/working-with-objects/annotations/">Annotations</a></p>
<!--</body>
</html>-->
content/en/docs/home/contribute/participating.md
-114
View File
@@ -1,114 +0,0 @@
---
title: Participating in SIG-DOCS
content_template: templates/concept
---
{{% capture overview %}}
SIG-DOCS is one of the [special interest groups](https://github.com/kubernetes/community/blob/master/sig-list.md) within the Kubernetes project, focused on writing, updating, and maintaining the documentation for Kubernetes as a whole.
{{% /capture %}}
{{% capture body %}}
SIG Docs welcomes content and reviews from all contributors. Anyone can open a pull request (PR), and anyone is welcome to comment on content or pull requests in progress.
Within the Kubernetes project, you may also become a member, reviewer, or approver.
These roles confer additional privileges and responsibilities when it comes to approving and committing changes.
See [community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md) for more information on how membership works within the Kubernetes community.
## Roles and Responsibilities
The automation reads `/hold`, `/lgtm`, and `/approve` comments and sets labels on the pull request.
When a pull request has the `lgtm` and `approve` labels without any `hold` labels, the pull request merges automatically.
Kubernetes org members, and reviewers and approvers for SIG Docs can add comments to control the merge automation.
- Members
Any member of the [Kubernetes organization](https://github.com/kubernetes) can review a pull request, and SIG Docs team members frequently request reviews from members of other SIGs for technical accuracy.
SIG Docs also welcomes reviews and feedback regardless of Kubernetes org membership.
You can indicate your approval by adding a comment of `/lgtm` to a pull request.
- Reviewers
Reviewers are individuals who review documentation pull requests.
Automation assigns reviewers to pull requests, and contributors can request a review with a comment on the pull request: `/assign [@_github_handle]`.
To indicate that a pull request requires no further changes, a reviewer should add comment to the pull request `/lgtm`.
A reviewer indicates technical accuracy with a `/lgtm` comment.
Reviewers can add a `/hold` comment to prevent the pull request from being merged.
Another reviewer or approver can remove a hold with the comment: `/hold cancel`.
When a reviewer is assigned a pull request to review it is not a sole responsibility, and any other reviewer may also offer their opinions on the pull request.
If a reviewer is requested, it is generally expected that the PR will be left to that reviewer to do their editorial pass on the content.
If a PR author or SIG Docs maintainer requests a review, refrain from merging or closing the PR until the requested reviewer completes their review.
- Approvers
Approvers have the ability to merge a PR.
Approvers can indicate their approval with a comment to the pull request: `/approve`.
An approver is indicating editorial approval with the an `/approve` comment.
Approvers can add a `/hold` comment to prevent the pull request from being merged.
Another reviewer or approver can remove a hold with the comment: `/hold cancel`.
Approvers may skip further reviews for small pull requests if the proposed changes appear trivial and/or well-understood.
An approver can indicate `/lgtm` or `/approve` in a PR comment to have a pull request merged, and all pull requests require at least one approver to provide their vote in order for the PR to be merged.
{{< note >}}**Note:** There is a special case when an approver uses the comment: `/lgtm`. In these cases, the automation will add both `lgtm` and `approve` tags, skipping any further review.
{{< /note >}}
For PRs that require no review (typos or otherwise trivial changes), approvers can enter an `lgtm` comment, indicating no need for further review and flagging the PR with approval to merge.
### Teams and groups within SIG Docs
You can get an overview of [SIG Docs from the community github repo](https://github.com/kubernetes/community/tree/master/sig-docs).
The SIG Docs group defines two teams on Github:
- [@kubernetes/sig-docs-maintainers](https://github.com/orgs/kubernetes/teams/sig-docs-maintainers)
- [@kubernetes/sig-docs-pr-reviews](https://github.com/orgs/kubernetes/teams/sig-docs-pr-reviews)
These groups maintain the [Kubernetes website repository](https://github.com/kubernetes/website), which houses the content hosted at this site.
Both can be referenced with their `@name` in github comments to communicate with everyone in that group.
These teams overlap, but do not exactly match, the groups used by the automation tooling.
For assignment of issues, pull requests, and to support PR approvals, the automation uses information from the OWNERS file.
To volunteer as a reviewer or approver, make a pull request and add your Github handle to the relevant section in the [OWNERS file](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md).
{{< note >}}
**Note:** Reviewers and approvers must meet requirements for participation.
For more information, see the [Kubernetes community](https://github.com/kubernetes/community/blob/master/community-membership.md#membership) repository.
{{< /note >}}
Documentation for the [OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md)
explains how to maintain OWNERS for each repository that enables it.
The [Kubernetes website repository](https://github.com/kubernetes/website) has two automation (prow) [plugins enabled](https://github.com/kubernetes/test-infra/blob/master/prow/plugins.yaml#L210):
- blunderbuss
- approve
These two plugins use the [OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS) and [OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES) files in our repo for configuration.
{{% /capture %}}
{{% capture whatsnext %}}
For more information about contributing to the Kubernetes documentation, see:
* Review the SIG Docs [Style Guide](/docs/home/contribute/style-guide/).
* Learn how to [stage your documentation changes](/docs/home/contribute/stage-documentation-changes/).
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/).
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
* How to generate documentation:
* Learn how to [generate Reference Documentation for Kubernetes Federation API](/docs/home/contribute/generated-reference/federation-api/)
* Learn how to [generate Reference Documentation for kubectl Commands](/docs/home/contribute/generated-reference/kubectl/)
* Learn how to [generate Reference Documentation for the Kubernetes API](/docs/home/contribute/generated-reference/kubernetes-api/)
* Learn how to [generate Reference Pages for Kubernetes Components and Tools](/docs/home/contribute/generated-reference/kubernetes-components/)
{{% /capture %}}
content/en/docs/home/contribute/review-issues.md
-104
View File
@@ -1,104 +0,0 @@
---
title: Reviewing Documentation Issues
content_template: templates/concept
---
{{% capture overview %}}
This page explains how documentation issues are reviewed and prioritized for the
<a href="https://github.com/kubernetes/website" target="_blank" class="_">kubernetes/website</a> repository. The purpose is to provide a way to organize issues and make it easier to contribute to Kubernetes documentation. The following should be used as the standard way of prioritizing, labeling, and interacting with issues.
{{% /capture %}}
{{% capture body %}}
## Categorizing issues
Issues should be sorted into different buckets of work using the following labels and definitions. If an issue doesn't have enough information to identify a problem that can be researched, reviewed, or worked on (i.e. the issue doesn't fit into any of the categories below) you should close the issue with a comment explaining why it is being closed.
### Needs Clarification
* Issues that need more information from the original submitter to make them actionable. Issues with this label that aren't followed up within a week may be closed.
### Actionable
* Issues that can be worked on with current information (or may need a comment to explain what needs to be done to make it more clear)
* Allows contributors to have easy to find issues to work on
### Needs Tech Review
* Issues that need more information in order to be worked on (the proposed solution needs to be proven, a subject matter expert needs to be involved, work needs to be done to understand the problem/resolution and if the issue is still relevant)
* Promotes transparency about level of work needed for the issue and that issue is in progress
### Needs Docs Review
* Issues that are suggestions for better processes or site improvements that require community agreement to be implemented
* Topics can be brought to SIG meetings as agenda items
### Needs UX Review
* Issues that are suggestions for improving the user interface of the site.
* Fixing broken site elements.
## Prioritizing Issues
The following labels and definitions should be used to prioritize issues. If you change the priority of an issues, please comment on the issue with your reasoning for the change.
### P1
* Major content errors affecting more than 1 page
* Broken code sample on a heavily trafficked page
* Errors on a “getting started” page
* Well known or highly publicized customer pain points
* Automation issues
### P2
* Default for all new issues
* Broken code for sample that is not heavily used
* Minor content issues in a heavily trafficked page
* Major content issues on a lower-trafficked page
### P3
* Typos and broken anchor links
## Handling special issue types
### Duplicate issues
If a single problem has one or more issues open for it, the problem should be consolidated into a single issue. You should decide which issue to keep open (or open a new issue), port over all relevant information, link related issues, and close all the other issues that describe the same problem. Only having a single issue to work on will help reduce confusion and avoid duplicating work on the same problem.
### Dead link issues
Depending on where the dead link is reported, different actions are required to resolve the issue. Dead links in the API and Kubectl docs are automation issues and should be assigned a P1 until the problem can be fully understood. All other dead links are issues that need to be manually fixed and can be assigned a P3.
### Support requests or code bug reports
Some issues opened for docs are instead issues with the underlying code, or requests for assistance when something (like a tutorial) didn't work. For issues unrelated to docs, close the issue with a comment directing the requester to support venues (Slack, Stack Overflow) and, if relevant, where to file an issue for bugs with features (kubernetes/kubernetes is a great place to start).
Sample response to a request for support:
```
This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](http://slack.k8s.io/). You can also search
resources like
[Stack Overflow](http://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.
You can also open issues for Kubernetes functionality in
https://github.com/kubernetes/kubernetes.
If this is a documentation issue, please re-open this issue.
```
Sample code bug report response:
```
This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.
If this is a documentation issue, please re-open this issue.
```
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/).
{{% /capture %}}
content/en/docs/home/contribute/style-guide.md
-393
View File
@@ -1,393 +0,0 @@
---
title: Documentation Style Guide
content_template: templates/concept
---
{{% capture overview %}}
This page gives writing style guidelines for the Kubernetes documentation.
These are guidelines, not rules. Use your best judgment, and feel free to
propose changes to this document in a pull request.
For additional information on creating new content for the Kubernetes
docs, follow the instructions on
[using page templates](/docs/home/contribute/page-templates/) and
[creating a documentation pull request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
{{% capture body %}}
{{< note >}}
**Note:** Kubernetes documentation uses [Blackfriday Markdown Renderer](https://github.com/russross/blackfriday) along with a few [Hugo Shortcodes](/docs/home/contribute/includes/) to support glossary entries, tabs, and representing feature state.
{{< /note >}}
## Language
Kubernetes documentation uses US English.
## Documentation formatting standards
### Use camel case for API objects
When you refer to an API object, use the same uppercase and lowercase letters
that are used in the actual object name. Typically, the names of API
objects use
[camel case](https://en.wikipedia.org/wiki/Camel_case).
Don't split the API object name into separate words. For example, use
PodTemplateList, not Pod Template List.
Refer to API objects without saying "object," unless omitting "object"
leads to an awkward construction.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>The Pod has two containers.</td><td>The pod has two containers.</td></tr>
<tr><td>The Deployment is responsible for ...</td><td>The Deployment object is responsible for ...</td></tr>
<tr><td>A PodList is a list of Pods.</td><td>A Pod List is a list of pods.</td></tr>
<tr><td>The two ContainerPorts ...</td><td>The two ContainerPort objects ...</td></tr>
<tr><td>The two ContainerStateTerminated objects ...</td><td>The two ContainerStateTerminateds ...</td></tr>
</table>
### Use angle brackets for placeholders
Use angle brackets for placeholders. Tell the reader what a placeholder
represents.
1. Display information about a pod:
kubectl describe pod <pod-name>
where `<pod-name>` is the name of one of your pods.
### Use bold for user interface elements
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Click <b>Fork</b>.</td><td>Click "Fork".</td></tr>
<tr><td>Select <b>Other</b>.</td><td>Select 'Other'.</td></tr>
</table>
### Use italics to define or introduce new terms
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>A <i>cluster</i> is a set of nodes ...</td><td>A "cluster" is a set of nodes ...</td></tr>
<tr><td>These components form the <i>control plane.</i></td><td>These components form the <b>control plane.</b></td></tr>
</table>
### Use code style for filenames, directories, and paths
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Open the <code>envars.yaml</code> file.</td><td>Open the envars.yaml file.</td></tr>
<tr><td>Go to the <code>/docs/tutorials</code> directory.</td><td>Go to the /docs/tutorials directory.</td></tr>
<tr><td>Open the <code>/_data/concepts.yaml</code> file.</td><td>Open the /_data/concepts.yaml file.</td></tr>
</table>
### Use the international standard for punctuation inside quotes
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>events are recorded with an associated "stage".</td><td>events are recorded with an associated "stage."</td></tr>
<tr><td>The copy is called a "fork".</td><td>The copy is called a "fork."</td></tr>
</table>
## Inline code formatting
### Use code style for inline code and commands
For inline code in an HTML document, use the `<code>` tag. In a Markdown
document, use the backtick (`).
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>The <code>kubectl run</code> command creates a Deployment.</td><td>The "kubectl run" command creates a Deployment.</td></tr>
<tr><td>For declarative management, use <code>kubectl apply</code>.</td><td>For declarative management, use "kubectl apply".</td></tr>
</table>
### Use code style for object field names
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Set the value of the <code>replicas</code> field in the configuration file.</td><td>Set the value of the "replicas" field in the configuration file.</td></tr>
<tr><td>The value of the <code>exec</code> field is an ExecAction object.</td><td>The value of the "exec" field is an ExecAction object.</td></tr>
</table>
### Use normal style for string and integer field values
For field values of type string or integer, use normal style without quotation marks.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Set the value of <code>imagePullPolicy</code> to Always.</td><td>Set the value of <code>imagePullPolicy</code> to "Always".</td></tr>
<tr><td>Set the value of <code>image</code> to nginx:1.8.</td><td>Set the value of <code>image</code> to <code>nginx:1.8</code>.</td></tr>
<tr><td>Set the value of the <code>replicas</code> field to 2.</td><td>Set the value of the <code>replicas</code> field to <code>2</code>.</td></tr>
</table>
## Code snippet formatting
### Don't include the command prompt
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>kubectl get pods</td><td>$ kubectl get pods</td></tr>
</table>
### Separate commands from output
Verify that the pod is running on your chosen node:
kubectl get pods --output=wide
The output is similar to this:
NAME READY STATUS RESTARTS AGE IP NODE
nginx 1/1 Running 0 13s 10.200.0.4 worker0
### Versioning Kubernetes examples
Code examples and configuration examples that include version information should be consistent with the accompanying text. Identify the Kubernetes version in the **Before you begin** section.
To specify the Kubernetes version for a task or tutorial page, include `min-kubernetes-server-version` in the front matter of the page.
If the example YAML is in a standalone file, find and review the topics that include it as a reference.
Verify that any topics using the standalone YAML have the appropriate version information defined.
If a stand-alone YAML file is not referenced from any topics, consider deleting it instead of updating it.
For example, if you are writing a tutorial that is relevant to Kubernetes version 1.8, the front-matter of your markdown file should look something like:
```yaml
---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---
```
In code and configuration examples, do not include comments about alternative versions.
Be careful to not include incorrect statements in your examples as comments, such as:
```yaml
apiVersion: v1 # earlier versions use...
kind: Pod
...
```
## Kubernetes.io word list
A list of Kubernetes-specific terms and words to be used consistently across the site.
<table>
<tr><th>Term</th><th>Usage</th></tr>
<tr><td>Kubernetes</td><td>Kubernetes should always be capitalized.</td></tr>
<tr><td>Docker</td><td>Docker should always be capitalized.</td></tr>
<tr><td>SIG Docs</td><td>SIG Docs rather than SIG-DOCS or other variations.</td></tr>
</table>
## Shortcodes
Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) help create different rhetorical appeal levels. Our documentation supports three different shortcodes in this category: **Note:** {{</* note */>}}, **Caution:** {{</* caution */>}}, and **Warning:** {{</* warning */>}}.
1. Surround the text with an opening and closing shortcode.
2. Use the following syntax to apply a style:
```
{{</* note */>}}
**Note:** The prefix you use is the same text you use in the tag.
{{</* /note */>}}
```
The output is:
{{< note >}}
**Note:** The prefix you choose is the same text for the tag.
{{< /note >}}
### Note
Use {{</* note */>}} to highlight a tip or a piece of information that may be helpful to know.
For example:
```
{{</* note */>}}
**Note:** You can _still_ use Markdown inside these callouts.
{{</* /note */>}}
```
The output is:
{{< note >}}
**Note:** You can _still_ use Markdown inside these callouts.
{{< /note >}}
### Caution
Use {{</* caution */>}} to call attention to an important piece of information to avoid pitfalls.
For example:
```
{{</* caution */>}}
**Caution:** The callout style only applies to the line directly above the tag.
{{</* /caution */>}}
```
The output is:
{{< caution >}}
**Caution:** The callout style only applies to the line directly above the tag.
{{< /caution >}}
### Warning
Use {{</* warning */>}} to indicate danger or a piece of information that is crucial to follow.
For example:
```
{{</* warning */>}}
**Warning:** Beware.
{{</* /warning */>}}
```
The output is:
{{< warning >}}
**Warning:** Beware.
{{< /warning >}}
## Common Shortcode Issues
### Ordered Lists
Shortcodes will interrupt numbered lists unless you indent four spaces before the notice and the tag.
For example:
1. Preheat oven to 350˚F
1. Prepare the batter, and pour into springform pan.
{{</* note */>}}**Note:** Grease the pan for best results.{{</* /note */>}}
1. Bake for 20-25 minutes or until set.
The output is:
1. Preheat oven to 350˚F
1. Prepare the batter, and pour into springform pan.
{{< note >}}**Note:** Grease the pan for best results.{{< /note >}}
1. Bake for 20-25 minutes or until set.
## Content best practices
This section contains suggested best practices for clear, concise, and consistent content.
### Use present tense
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>This command starts a proxy.</td><td>This command will start a proxy.</td></tr>
</table>
Exception: Use future or past tense if it is required to convey the correct
meaning.
### Use active voice
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>You can explore the API using a browser.</td><td>The API can be explored using a browser.</td></tr>
<tr><td>The YAML file specifies the replica count.</td><td>The replica count is specified in the YAML file.</td></tr>
</table>
Exception: Use passive voice if active voice leads to an awkward construction.
### Use simple and direct language
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>To create a ReplicaSet, ...</td><td>In order to create a ReplicaSet, ...</td></tr>
<tr><td>See the configuration file.</td><td>Please see the configuration file.</td></tr>
<tr><td>View the Pods.</td><td>With this next command, we'll view the Pods.</td></tr>
</table>
### Address the reader as "you"
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>You can create a Deployment by ...</td><td>We'll create a Deployment by ...</td></tr>
<tr><td>In the preceding output, you can see...</td><td>In the preceding output, we can see ...</td></tr>
</table>
### Avoid Latin phrases
Prefer English terms over Latin abbreviations.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>For example, ...</td><td>e.g., ...</td></tr>
<tr><td>That is, ...</td><td>i.e., ...</td></tr>
</table>
Exception: Use "etc." for et cetera.
## Patterns to avoid
### Avoid using "we"
Using "we" in a sentence can be confusing, because the reader might not know
whether they're part of the "we" you're describing.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Version 1.4 includes ...</td><td>In version 1.4, we have added ...</td></tr>
<tr><td>Kubernetes provides a new feature for ...</td><td>We provide a new feature ...</td></tr>
<tr><td>This page teaches you how to use pods.</td><td>In this page, we are going to learn about pods.</td></tr>
</table>
### Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>Internally, ...</td><td>Under the hood, ...</td></tr>
<tr><td>Create a new cluster.</td><td>Turn up a new cluster.</td></tr>
</table>
### Avoid statements about the future
Avoid making promises or giving hints about the future. If you need to talk about
an alpha feature, put the text under a heading that identifies it as alpha
information.
### Avoid statements that will soon be out of date
Avoid words like "currently" and "new." A feature that is new today might not be
considered new in a few months.
<table>
<tr><th>Do</th><th>Don't</th></tr>
<tr><td>In version 1.4, ...</td><td>In the current version, ...</td></tr>
<tr><td>The Federation feature provides ...</td><td>The new Federation feature provides ...</td></tr>
</table>
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
content/en/docs/home/contribute/write-new-topic.md
-167
View File
@@ -1,167 +0,0 @@
---
title: Writing a New Topic
content_template: templates/task
---
{{% capture overview %}}
This page shows how to create a new topic for the Kubernetes docs.
{{% /capture %}}
{{% capture prerequisites %}}
Create a fork of the Kubernetes documentation repository as described in
[Creating a Documentation Pull Request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}
{{% capture steps %}}
## Choosing a page type
As you prepare to write a new topic, think about which of these page types
is the best fit for your content:
<table>
<tr>
<td>Task</td>
<td>A task page shows how to do a single thing. The idea is to give readers a sequence of steps that they can actually do as they read the page. A task page can be short or long, provided it stays focused on one area. In a task page, it is OK to blend brief explanations with the steps to be performed, but if you need to provide a lengthy explanation, you should do that in a concept topic. Related task and concept topics should link to each other. For an example of a short task page, see <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">Configure a Pod to Use a Volume for Storage</a>. For an example of a longer task page, see <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">Configure Liveness and Readiness Probes</a></td>
</tr>
<tr>
<td>Tutorial</td>
<td>A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.</td>
</tr>
<tr>
<td>Concept</td>
<td>A concept page explains some aspect of Kubernetes. For example, a concept page might describe the Kubernetes Deployment object and explain the role it plays as an application is deployed, scaled, and updated. Typically, concept pages don't include sequences of steps, but instead provide links to tasks or tutorials. For an example of a concept topic, see <a href="/docs/concepts/architecture/nodes/">Nodes</a>.</td>
</tr>
</table>
Each page type has a
[template](/docs/home/contribute/page-templates/)
that you can use as you write your topic.
Using templates helps ensure consistency among topics of a given type.
## Choosing a title and filename
Choose a title that has the keywords you want search engines to find.
Create a filename that uses the words in your title separated by hyphens.
For example, the topic with title
[Using an HTTP Proxy to Access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/)
has filename `http-proxy-access-api.md`. You don't need to put
"kubernetes" in the filename, because "kubernetes" is already in the
URL for the topic, for example:
http://kubernetes.io/docs/tasks/access-kubernetes-api/http-proxy-access-api/
## Adding the topic title to the front matter
In your topic, put a `title` field in the
[front matter](https://jekyllrb.com/docs/frontmatter/).
The front matter is the YAML block that is between the
triple-dashed lines at the top of the page. Here's an example:
---
title: Using an HTTP Proxy to Access the Kubernetes API
---
## Choosing a directory
Depending on your page type, put your new file in a subdirectory of one of these:
* /docs/tasks/
* /docs/tutorials/
* /docs/concepts/
You can put your file in an existing subdirectory, or you can create a new
subdirectory.
## Creating an entry in the table of contents
Depending page type, create an entry in one of these files:
* /_data/tasks.yaml
* /_data/tutorials.yaml
* /_data/concepts.yaml
Here's an example of an entry in /_data/tasks.yaml:
- docs/tasks/configure-pod-container/configure-volume-storage.md
## Embedding code in your topic
If you want to include some code in your topic, you can embed the code in your
file directly using the markdown code block syntax. This is recommended for the
following cases (not an exhaustive list):
- The code is showing the output from a command such as
`kubectl get deploy mydeployment -o json | jq '.status'`.
- The code is not generic enough for users to try out. As an example, the YAML
file for creating a Pod which depends on a specific
[FlexVolume](/docs/concepts/storage/volumes#flexvolume) implementation can be
directly embedded into the topic when appropriate.
- The code is an incomplete example because its purpose is to highlight a
portion of an otherwise large file. For example, when describing ways to
customize the [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)
for some reasons, you may provide a short snippet directly in your topic file.
- The code is not meant for users to try out due to other reasons. For example,
when describing how a new attribute should be added to a resource using the
`kubectl edit` command, you may provide a short example that includes only
the attribute to add.
## Including code from another file
Another way to include code in your topic is to create a new, complete sample
file (or a group of sample files) and then reference the sample(s) from your
topic. This is the preferred way of including sample YAML files when the sample
is generic, reusable, and you want the readers to try it out by themselves.
When adding a new standalone sample file (e.g. a YAML file), place the code in
one of the `<LANG>/examples/` subdirectories where `<LANG>` is the language for
the topic. In your topic file, use the `codenew` shortcode:
<pre>&#123;&#123;&lt; codenew file="&lt;RELPATH&gt;/my-example-yaml&gt;" &gt;&#125;&#125;</pre>
where `<RELPATH>` is the path to the file you're including, relative to the
`examples` directory. For example, the following short code references a YAML
file located at `content/en/examples/pods/storage/gce-volume.yaml`.
<pre>&#123;&#123;&lt; codenew file="pods/storage/gce-volume.yaml" &gt;&#125;&#125;</pre>
## Showing how to create an API object from a configuration file
If you need to show the reader how to create an API object based on a
configuration file, place the configuration file in one of the subdirectories
under `<LANG>/examples`.
In your topic, show this command:
```
kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
```
{{< note >}}
**NOTE**: When adding new YAML files to the `<LANG>/examples` directory, make
sure the file is also included into the `<LANG>/examples_test.go` file. The
Travis CI for the Website automatically runs this test case when PRs are
submitted to ensure all examples pass the tests.
{{< /note >}}
For an example of a topic that uses this technique, see
[Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/).
## Adding images to a topic
Put image files in the `/images` directory. The preferred
image format is SVG.
{{% /capture %}}
{{% capture whatsnext %}}
* Learn about [using page templates](/docs/home/contribute/page-templates/).
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/).
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
{{% /capture %}}