Merge pull request #1861 from steveperry-53/readme
Move README content to contribution section.reviewable/pr1875/r3^2
Steve Perry
GitHub
commit
89c6b0abee
175
README.md
175
README.md
|
|
@ -1,182 +1,19 @@
|
|||
## Instructions for Contributing to the Docs/Website
|
||||
## Instructions for Contributing to the Kubernetes Documentation
|
||||
|
||||
Welcome! We are very pleased you want to contribute to the documentation and/or website for Kubernetes.
|
||||
Welcome! We are very pleased you want to contribute to the Kubernetes documentation.
|
||||
|
||||
You can click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it.
|
||||
You can click the **Fork** button in the upper-right area of the screen to create a copy of this repository in your GitHub account called a *fork*. Make any changes you want in your fork, and when you are ready to send those changes to us, go to your fork and create a new pull request to let us know about it.
|
||||
|
||||
For more information about contributing to the Kubernetes documentation, see:
|
||||
|
||||
* [Contributing to the kubernetes Documentation](http://kubernetes.io/editdocs/)
|
||||
* [Creating a Documentation Pull Request](http://kubernetes.io/docs/contribute/create-pull-request/)
|
||||
* [Writing a New Topic](http://kubernetes.io/docs/contribute/write-new-topic/)
|
||||
* [Staging Your Documentation Changes](http://kubernetes.io/docs/contribute/stage-documentation-changes/)
|
||||
* [Using Page Templates](http://kubernetes.io/docs/contribute/page-templates/)
|
||||
|
||||
## Automatic Staging for Pull Requests
|
||||
|
||||
When you create a pull request (either against master or the upcoming release), your changes are staged in a custom subdomain on Netlify so that you can see your changes in rendered form before the PR is merged. You can use this to verify that everything is correct before the PR gets merged. To view your changes:
|
||||
|
||||
- Scroll down to the PR's list of Automated Checks
|
||||
- Click "Show All Checks"
|
||||
- Look for "deploy/netlify"; you'll see "Deploy Preview Ready!" if staging was successful
|
||||
- Click "Details" to bring up the staged site and navigate to your changes
|
||||
|
||||
## Branch structure and staging
|
||||
|
||||
The current version of the website is served out of the `master` branch. To make changes to the live docs, such as bug fixes, broken links, typos, etc, **target your pull request to the master branch**
|
||||
|
||||
The `release-1.x` branch stores changes for **upcoming releases of Kubernetes**. For example, the `release-1.5` branch has changes for the 1.5 release. These changes target branches (and *not* master) to avoid publishing documentation updates prior to the release for which they're relevant. If you have a change for an upcoming release of Kubernetes, **target your pull request to the appropriate release branch**.
|
||||
|
||||
The staging site for the next 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.
|
||||
|
||||
## Staging the site locally (using Docker)
|
||||
|
||||
Don't like installing stuff? Download and run a local staging server with a single `docker run` command.
|
||||
|
||||
git clone https://github.com/kubernetes/kubernetes.github.io.git
|
||||
cd kubernetes.github.io
|
||||
docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.0
|
||||
|
||||
Then visit [http://localhost:4000](http://localhost:4000) to see our site. Any changes you make on your local machine will be automatically staged.
|
||||
|
||||
If you're interested you can view [the Dockerfile for this image](https://github.com/kubernetes/kubernetes.github.io/blob/master/staging-container/Dockerfile).
|
||||
|
||||
## Staging the site locally (from scratch setup)
|
||||
|
||||
The below commands to setup your environment for running GitHub pages locally. Then, any edits you make will be viewable
|
||||
on a lightweight webserver that runs on your local machine.
|
||||
|
||||
This will typically be the fastest way (by far) to iterate on docs changes and see them staged, once you get this set up, but it does involve several install steps that take awhile to complete, and makes system-wide modifications.
|
||||
|
||||
Install Ruby 2.2 or higher. If you're on Linux, run these commands:
|
||||
|
||||
apt-get install software-properties-common
|
||||
apt-add-repository ppa:brightbox/ruby-ng
|
||||
apt-get install ruby2.2
|
||||
apt-get install ruby2.2-dev
|
||||
|
||||
* If you're on a Mac, follow [these instructions](https://gorails.com/setup/osx/).
|
||||
* If you're on a Windows machine you can use the [Ruby Installer](http://rubyinstaller.org/downloads/). During the installation make sure to check the option for *Add Ruby executables to your PATH*.
|
||||
|
||||
The remainder of the steps should work the same across operating systems.
|
||||
|
||||
To confirm you've installed Ruby correctly, at the command prompt run `gem --version` and you should get a response with your version number. Likewise you can confirm you have Git installed properly by running `git --version`, which will respond with your version of Git.
|
||||
|
||||
Install the GitHub Pages package, which includes Jekyll:
|
||||
|
||||
gem install github-pages
|
||||
|
||||
Clone our site:
|
||||
|
||||
git clone https://github.com/kubernetes/kubernetes.github.io.git
|
||||
|
||||
Make any changes you want. Then, to see your changes locally:
|
||||
|
||||
cd kubernetes.github.io
|
||||
jekyll serve
|
||||
|
||||
Your copy of the site will then be viewable at: [http://localhost:4000](http://localhost:4000)
|
||||
(or wherever Jekyll tells you).
|
||||
|
||||
## GitHub help
|
||||
|
||||
If you're a bit rusty with git/GitHub, you might want to read
|
||||
[this](http://readwrite.com/2013/10/02/github-for-beginners-part-2) for a refresher.
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Edit Page Titles or Change the Left Navigation
|
||||
|
||||
Edit the yaml files in `/_data/` for the Guides, Reference, Samples, or Support areas.
|
||||
|
||||
You may have to exit and `jekyll clean` before restarting the `jekyll serve` to
|
||||
get changes to files in `/_data/` to show up.
|
||||
|
||||
### Add Images
|
||||
|
||||
Put the new image in `/images/docs/` if it's for the documentation, and just `/images/` if it's for the website.
|
||||
|
||||
**For diagrams, we greatly prefer SVG files!**
|
||||
|
||||
### Include code from another file
|
||||
|
||||
To include a file that is hosted on this GitHub repo, insert this code:
|
||||
|
||||
<pre>{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="<PATHFROMROOT>" %}</pre>
|
||||
|
||||
* `LEXERVALUE`: The language in which the file was written; must be [a value supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers).
|
||||
* `RELATIVEPATH`: The path to the file you're including, relative to the current file.
|
||||
* `PATHFROMROOT`: The path to the file relative to root, e.g. `/docs/admin/foo.yaml`
|
||||
|
||||
To include a file that is hosted in the external, main Kubernetes repo, make sure it's added to [/update-imported-docs.sh](https://github.com/kubernetes/kubernetes.github.io/blob/master/update-imported-docs.sh), and run it so that the file gets downloaded, then enter:
|
||||
|
||||
<pre>{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" k8slink="<PATHFROMK8SROOT>" %}</pre>
|
||||
|
||||
* `PATHFROMK8SROOT`: The path to the file relative to the root of [the Kubernetes repo](https://github.com/kubernetes/kubernetes/tree/release-1.2), e.g. `/examples/rbd/foo.yaml`
|
||||
|
||||
## Using tabs for multi-language examples
|
||||
|
||||
By specifying some inline CSV in a varable called `tabspec`, you can include a file
|
||||
called `tabs.html` that generates tabs showing code examples in multiple langauges.
|
||||
|
||||
<pre>{% capture tabspec %}servicesample
|
||||
JSON,json,service-sample.json,/docs/user-guide/services/service-sample.json
|
||||
YAML,yaml,service-sample.yaml,/docs/user-guide/services/service-sample.yaml{% endcapture %}
|
||||
{% include tabs.html %}</pre>
|
||||
|
||||
In English, this would read: "Create a set of tabs with the alias `servicesample`,
|
||||
and have tabs visually labeled "JSON" and "YAML" that use `json` and `yaml` Rouge syntax highlighting, which display the contents of
|
||||
`service-sample.{extension}` on the page, and link to the file in GitHub at (full path)."
|
||||
|
||||
Example file: [Pods: Multi-Container](http://kubernetes.io/docs/user-guide/pods/multi-container/).
|
||||
|
||||
## Use a global variable
|
||||
|
||||
The `/_config.yml` file defines some useful variables you can use when editing docs.
|
||||
|
||||
* `page.githubbranch`: The name of the GitHub branch on the Kubernetes repo that is associated with this branch of the docs. e.g. `release-1.2`
|
||||
* `page.version` The version of Kubernetes associated with this branch of the docs. e.g. `v1.2`
|
||||
* `page.docsbranch` The name of the GitHub branch on the Docs/Website repo that you are currently using. e.g. `release-1.1` or `master`
|
||||
|
||||
This keeps the docs you're editing aligned with the Kubernetes version you're talking about. For example, if you define a link like so, you'll never have to worry about it going stale in future doc branches:
|
||||
|
||||
<pre>View the README [here](http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/README.md).</pre>
|
||||
|
||||
That, of course, will send users to:
|
||||
|
||||
[http://releases.k8s.io/release-1.2/cluster/addons/README.md](http://releases.k8s.io/release-1.2/cluster/addons/README.md)
|
||||
|
||||
(Or whatever Kubernetes release that docs branch is associated with.)
|
||||
|
||||
## Config yaml guidelines
|
||||
|
||||
Guidelines for config yamls that are included in the site docs. These
|
||||
are the yaml or json files that contain Kubernetes object
|
||||
configuration to be used with `kubectl create -f` Config yamls should
|
||||
be:
|
||||
|
||||
* Separate deployable files, not embedded in the document, unless very
|
||||
small variations of a full config.
|
||||
* Included in the doc with the include code
|
||||
[above.](#include-code-from-another-file)
|
||||
* In the same directory as the doc that they are being used in
|
||||
* If you are re-using a yaml from another doc, that is OK, just
|
||||
leave it there, don't move it up to a higher level directory.
|
||||
* Tested in
|
||||
[test/examples_test.go](https://github.com/kubernetes/kubernetes.github.io/blob/master/test/examples_test.go)
|
||||
* Follows
|
||||
[best practices.](http://kubernetes.io/docs/user-guide/config-best-practices/)
|
||||
|
||||
Don't assume the reader has this repository checked out, use `kubectl
|
||||
create -f https://github...` in example commands. For Docker images
|
||||
used in config yamls, try to use an image from an existing Kubernetes
|
||||
example. If creating an image for a doc, follow the
|
||||
[example guidelines](https://github.com/kubernetes/kubernetes/blob/master/examples/guidelines.md#throughout)
|
||||
section on "Docker images" from the Kubernetes repository.
|
||||
|
||||
## Partners
|
||||
Kubernetes partners refers to the companies who contribute to the Kubernetes core codebase, extend their platform to support Kubernetes or provide managed services to users centered around the Kubernetes platform. Partners can get their services and offerings added to the [partner page](https://k8s.io/partners) by completing and submitting the [partner request form](https://goo.gl/qcSnZF). Once the information and assets are verified, the partner product/services will be listed in the partner page. This would typically take 7-10 days.
|
||||
* [Documentation Style Guide](http://kubernetes.io/docs/contribute/style-guide/)
|
||||
|
||||
## Thank you!
|
||||
|
||||
Kubernetes thrives on community participation and we really appreciate your
|
||||
Kubernetes thrives on community participation, and we really appreciate your
|
||||
contributions to our site and our documentation!
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@ toc:
|
|||
|
||||
- title: Contributing to the Kubernetes Docs
|
||||
section:
|
||||
- title: Contributing to the Kubernetes Documentation
|
||||
path: /editdocs/
|
||||
- title: Creating a Documentation Pull Request
|
||||
path: /docs/contribute/create-pull-request/
|
||||
- title: Writing a New Topic
|
||||
|
|
@ -51,5 +53,3 @@ toc:
|
|||
path: https://github.com/kubernetes/kubernetes/releases/
|
||||
- title: Release Roadmap
|
||||
path: https://github.com/kubernetes/kubernetes/milestones/
|
||||
- title: Contributing to Kubernetes Documentation
|
||||
path: /editdocs/
|
||||
|
|
|
|||
|
|
@ -80,6 +80,12 @@ site where you can verify that your changes have rendered correctly.
|
|||
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.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
|
|
|
|||
|
|
@ -33,16 +33,18 @@ the master branch.
|
|||
|
||||
### Staging a pull request
|
||||
|
||||
When you create pull request against the Kubernetes documentation
|
||||
repository, you can see your changes on a staging server.
|
||||
When you create a pull request, either against the master or <vnext>
|
||||
branch, your changes are staged in a custom subdomain on Netlify so that
|
||||
you can see your changes in rendered form before the pull request is merged.
|
||||
|
||||
1. In your GitHub account, in your new branch, submit a pull request to the
|
||||
kubernetes/kubernetes.github.io 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 see your changes.
|
||||
1. Scroll down to the list of automated checks. 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 see your changes.
|
||||
|
||||
### Staging locally using Docker
|
||||
|
||||
|
|
|
|||
|
|
@ -34,7 +34,7 @@ is the best fit for your content:
|
|||
<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.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
</table>
|
||||
|
||||
Each page type has a
|
||||
[template](/docs/contribute/page-templates/)
|
||||
|
|
@ -72,6 +72,50 @@ Depending page type, create an entry in one of these files:
|
|||
* /_data/tutorials.yaml
|
||||
* /_data/concepts.yaml
|
||||
|
||||
### Including code from another file
|
||||
|
||||
To include a code file in your topic, place the code file in the Kubernetes
|
||||
documentation repository, preferably in the same directory as your topic
|
||||
file. In your topic file, use the `include` tag:
|
||||
|
||||
<pre>{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="/<PATHFROMROOT>" %}</pre>
|
||||
|
||||
where:
|
||||
|
||||
* `<LEXERVALUE>` is the language in which the file was written. This must be
|
||||
[a value supported by Rouge](https://github.com/jneen/rouge/wiki/list-of-supported-languages-and-lexers).
|
||||
* `<RELATIVEPATH>` is the path to the file you're including, relative to the current file, for example, `gce-volume.yaml`.
|
||||
* `<PATHFROMROOT>` is the path to the file relative to root, for example, `docs/tutorials/stateful-application/gce-volume.yaml`.
|
||||
|
||||
Here's an example of using the `include` tag:
|
||||
|
||||
<pre>{% include code.html language="yaml" file="gce-volume.yaml" ghlink="/docs/tutorials/stateful-application/gce-volume.yaml" %}</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 the Kubernetes documentation
|
||||
repository, preferably in the same directory as your topic file.
|
||||
|
||||
In your topic, show this command:
|
||||
|
||||
kubectl create -f http://k8s.io/<PATHFROMROOT>
|
||||
|
||||
where `<PATHFROMROOT>` is the path to the configuration file relative to root,
|
||||
for example, `docs/tutorials/stateful-application/gce-volume.yaml`.
|
||||
|
||||
Here's an example of a command that creates an API object from a configuration file:
|
||||
|
||||
kubectl create -f http://k8s.io/docs/tutorials/stateful-application/gce-volume.yaml
|
||||
|
||||
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.
|
||||
|
||||
{% endcapture %}
|
||||
|
||||
{% capture whatsnext %}
|
||||
|
|
|
|||
13
editdocs.md
13
editdocs.md
|
|
@ -22,7 +22,7 @@ $( document ).ready(function() {
|
|||
|
||||
<h2>Continue your edit</h2>
|
||||
|
||||
<p>Click the below link to edit the page you were just on. When you are done, press "Commit Changes" at the bottom of the screen. This will create a copy of our site on your GitHub account called a "fork." You can make other changes in your fork after it is created, if you want. When you are ready to send us all your changes, go to the index page for your fork and click "New Pull Request" to let us know about it.</p>
|
||||
<p>Click the button below to edit the page you were just on. When you are done, click <b>Commit Changes</b> at the bottom of the screen. This creates a copy of our site in your GitHub account called a <i>fork</i>. You can make other changes in your fork after it is created, if you want. When you are ready to send us all your changes, go to the index page for your fork and click <b>New Pull Request</b> to let us know about it.</p>
|
||||
|
||||
<p><a id="continueEditButton" class="button"></a></p>
|
||||
|
||||
|
|
@ -31,12 +31,19 @@ $( document ).ready(function() {
|
|||
|
||||
<h2>Edit our site in the cloud</h2>
|
||||
|
||||
<p>Click the below button to visit the repo for our site. You can then click the "Fork" button in the upper-right area of the screen to create a copy of our site on your GitHub account called a "fork." Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click "New Pull Request" to let us know about it.</p>
|
||||
<p>Click the button below to visit the repo for our site. You can then click the <b>Fork</b> button in the upper-right area of the screen to create a copy of our site in your GitHub account called a <i>fork</i>. Make any changes you want in your fork, and when you are ready to send those changes to us, go to the index page for your fork and click <b>New Pull Request</b> to let us know about it.</p>
|
||||
|
||||
<p><a class="button" href="https://github.com/kubernetes/kubernetes.github.io/">Browse this site's source code</a></p>
|
||||
|
||||
</div>
|
||||
<!-- END: Dynamic section -->
|
||||
|
||||
<br/>
|
||||
|
||||
{% include_relative README.md %}
|
||||
For more information about contributing to the Kubernetes documentation, see:
|
||||
|
||||
* [Creating a Documentation Pull Request](http://kubernetes.io/docs/contribute/create-pull-request/)
|
||||
* [Writing a New Topic](http://kubernetes.io/docs/contribute/write-new-topic/)
|
||||
* [Staging Your Documentation Changes](http://kubernetes.io/docs/contribute/stage-documentation-changes/)
|
||||
* [Using Page Templates](http://kubernetes.io/docs/contribute/page-templates/)
|
||||
* [Documentation Style Guide](http://kubernetes.io/docs/contribute/style-guide/)
|
||||
|
|
|
|||
|
|
@ -14,7 +14,11 @@ title: Partners
|
|||
|
||||
<section id="users">
|
||||
<main>
|
||||
<<<<<<< HEAD
|
||||
<h5>We are working with a broad group of partners who contribute to the Kubernetes core codebase, making it stronger and richer. These partners create a vibrant Kubernetes ecosystem supporting a spectrum of complementing platforms, from open source solutions to market-leading technologies.</h5>
|
||||
=======
|
||||
<h5>We are working with a broad group of partners who contribute to the Kubernetes core codebase, making it stronger and richer. There partners create a vibrant Kubernetes ecosystem supporting a spectrum of complementing platforms, from open source solutions to market-leading technologies. Partners can get their services and offerings added to this page by completing and submitting the <a href="https://goo.gl/qcSnZF">partner request form</a>.</h5>
|
||||
>>>>>>> ebaa392... Addressed comments by jaredbhatti.
|
||||
<h3>Technology Partners</h3>
|
||||
<div id="isvContainer"></div>
|
||||
<h3>Services Partners</h3>
|
||||
|
|
|
|||
Loading…
Reference in New Issue