kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #723 from pwittrock/templatedd 

More udpates to how to use templates.
pull/677/merge
Phillip Wittrock 2016-06-24 16:29:20 -07:00 committed by GitHub
parent 6fc80c3aa2 a6ba113db9
commit 67ab589815
1 changed files with 105 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
docs/templatedemos/index.md
View File

@ -10,129 +10,121 @@ $(function() {
Check out the kubernetes/kubernetes.github.io repo and the docsv2 branch.
## Step 1: Fork and Clone the repo
### Step 1: Fork and Clone the repo
- Fork [kubernetes/kubernetes.github.io](https://github.com/kubernetes/kubernetes.github.io)
- [Setup your GitHub authentication using ssh](https://help.github.com/articles/generating-an-ssh-key/)
- Clone the repo under go/src/k8s.io
- Clone the repo under ~/go/src/k8s.io
```sh
```shell
cd ~/go/src/k8s.io
git clone git@github.com:<you-github-repo>/kubernetes.github.io
cd kubernetes.github.io
git remote add upstream https://github.com/kubernetes/kubernetes.github.io.git
```
## Step 2: Move to the docsv2 branch
Docs v2 development is being performed in the docsv2 branch. This is the branch
### Step 2: Switch to the docsv2 branch
Docs v2 development is being performed in the `docsv2` branch. This is the branch
you want to be working from.
From ~/go/src/k8s.io/kubernetes.github.io
From ~/go/src/k8s.io/kubernetes.github.io:
```shell
git checkout -b docsv2 # switch to the docsv2 branch
git fetch upstream # get the latest upstream changes
git reset --hard upstream/docsv2 # sync the branch to upstream
git checkout -b docsv2
git fetch upstream
git reset --hard upstream/docsv2
```
## Step 3: Make sure you can serve rendered docs locally from your dev box
### Step 3: Make sure you can serve rendered docs locally from your dev box
- [Follow the editdocs instructions](http://kubernetes.io/editdocs/)
# Writing Docs Using Templates
<div id="accordion">
<h3>Concept Overviews</h3>
## Types of Templates
- Concept Template
- Introduce K8s Api Objects e.g. Pod
- Task Template
- Step-by-step guide for "Doing X".
- Useful for breaking down various ways of configuring Concepts into sub-topics
- Landing Pages Template
- Collection of click-able cards on a grid
- Useful for directing users to actual content from a visual Table of Contents
# Concept Overview Template Details
<div>{% capture instructions %}
A concept overview covers the most essential, important information about core
Kubernetes concepts and features. Examples of Concepts include `Pod`,
`Deployment`, `Service`, etc.
### Example
## Reference Examples
- [Source Link](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md)
- [Rendered Link](filledout/)
- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md)
- [Link to Rendered Template](filledout/)
### Usage
## Usage
To create a new concept overview page, create a new file under
`docs/your-concept-name/index.md`.
### Creating the file
The file should start with the set of tags to apply to the concept and end
with an `include templates/concept-overview.md` block.
To create a new concept overview page, create a new directory with the concept
name under the docs directory and an index.md file.
e.g. `docs/your-concept-name/index.md`.
The file needs to have the following `capture` sections:
### Adding the Template sections
- concept
- when_to_use
- when_not_to_use
- status
- usage
- tags
```liquid{% raw %}
---
add
include
tags
here
e.g.
pod
---
{% capture concept %}
Name of the Concept goes here (e.g. Pod)
{% endcapture %}
```
{% capture what_is %}
1 sentence description of the Concept that describes the function it performs.
If needed:
- add
- clarifying
- bullet points
- concept: the concept name e.g. Pod
![Also add a diagram](/images/docs/file.svg){: style="max-width: 25%" }
``` #
{% capture concept %}{% endcapture %}
```
{% comment %}
Include a comment indicating where an editable image exists:
https://drive.google.com/open?id=1pQe4-s76fqyrzB8f3xoJo4MPLNVoBlsE1tT9MyLNINg
{% endcomment %}
{% endcapture %}
- what_is: one sentence description the function / role of the concept. Diagrams are helpful.
{% capture when_to_use %}
Clarify precisely when and how to use this Concept. Disambiguate when to use
this instead of similar concepts. e.g. Secret vs ConfigMap,
Deployment vs Job vs other controllers, Service vs Ingress.
``` #
{% capture what_is %}{% endcapture %}
```
| Tables | Can Be |
|------------|----------------|
| Helpful | When |
| Comparing | Functionality |
| Across | Concepts |
{% endcapture %}
- when_to_use: disambiguate when to use this vs alternatives
{% capture when_not_to_use %}
Call out common anti-patterns to be avoided.
{% endcapture %}
``` #
{% capture when_to_use %}{% endcapture %}
```
{% capture status %}
Describe how to get the current status of an instance in a cluster using kubectl
- when_not_to_use: highlight common anti-patterns
Use a table to clarify the response.
``` #
{% capture when_not_to_use %}{% endcapture %}
```
Consider status from kubectl describe as well.
{% endcapture %}
- status: how to get the status for this object using kubectl
{% capture usage %}
If the concept interacts with or is embedded in other Concepts, clarify that here.
For Services this should call out the meaning of the label selectors, for Volumes
this should call out that they are defined within a Pod.
``` #
{% capture status %}{% endcapture %}
```
Include the example yaml here
{% endcapture %}
- usage: example yaml
``` #
{% capture usage %}{% endcapture %}
```
- template: include the template at the end
``` #
{% include templates/concept-overview.md %}
{% endraw %}```
### Adding page to navigation
### Adding the page to navigation
Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `concepts.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page.
@ -141,46 +133,74 @@ Once your page is saved, somewhere in the `/docs/` directory, add a reference to
</div>
<h3>Task</h3>
# Task Template Details
<div>{% capture instructions %}
A task page offers step-by-step instructions for completing a task with Kubernetes. **A task page should be narrowly focused on task completion and not delve into concepts or reference information.**
### Demos
- [Blank](blanktask/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blanktask.md))
- [Filled Out](task/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/task.md))
## Example
- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/task.md)
- [Link to Rendered Page](task/)
### Usage
## Creating the file
To create a new task page, create a file under docs/tasks/task-name.
e.g. `docs/tasks/your-task-name`.
### Adding the Template sections
- tags
```liquid{% raw %}
---
tags
---
```
- purpose: one sentence description of the task and motivation
``` #
{% capture purpose %}{% endcapture %}
```
- recommended_background: List of Concepts referenced or other Tasks, Tutorials that provide needed context
``` #
{% capture recommended_background %}{% endcapture %}
```
- set_by_step: Add multiple sections. 1 per step in the task.
``` #
{% capture step_by_step %}{% endcapture %}
```
- template: include the template at the end
``` #
{% include templates/task.md %}
{% endraw %}```
### Adding page to navigation
### Adding the page to navigation
Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `tasks.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page.
Add a reference to the `tasks.yml` file under `/_data/` so that it will appear in the left-hand navigation of the site. This is also where you add a title to the page.
{% endcapture %}
{{ instructions | markdownify }}
</div>
<h3>Landing Pages</h3>
# Landing Pages
<div>{% capture instructions %}
Landing pages are a set of clickable "cards" arranged in a grid. Each card has a heading and description, and optioninall, a thumbnail image. They are meant to be index pages that quickly forward users on to deeper content.
### Demos
- [Blank](blanklanding/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blanklanding.md))
- [Filled Out](landingpage/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/landingpage.md))
- [Link to Example Landing Page](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/landingpage.md)
- [Link to Rendered Landing Page](landingpage/)
### Usage
@ -209,14 +229,14 @@ Once your page is saved, somewhere in the `/docs/` directory, add a reference to
</div>
<h3>kubectl yaml</h3>
# kubectl yaml
<div>{% capture instructions %}
You probably shouldn't be using this, but we also have templates which consume YAML files that are generated by the Kubernetes authors. These are turned into pages which display the reference information for the various CLI tools.
### Demos
- [Blank](blankkubectl/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blankkubectl.md))
- [Filled Out](kubectl/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/kubectl.md))
- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/kubectl.md)
- [Link to Rendered Template](kubectl/)
### Adding page to navigation