From a643ed6e0d8d2b13893aca3e99094985e809f14d Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Wed, 22 Jun 2016 22:12:58 -0700 Subject: [PATCH] Add more detail to Template docs. --- docs/templatedemos/index.md | 135 ++++++++++++++++++++++++++++++------ 1 file changed, 115 insertions(+), 20 deletions(-) diff --git a/docs/templatedemos/index.md b/docs/templatedemos/index.md index 30bee2839c..a202795fd9 100644 --- a/docs/templatedemos/index.md +++ b/docs/templatedemos/index.md @@ -5,41 +5,136 @@ $(function() { $( "#accordion" ).accordion(); }); - -# Template Demos +# Before you Begin: Get the docs code checked out locally + +Check out the kubernetes/kubernetes.github.io repo and the docsv2 branch. + +## 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 + +```sh +cd ~/go/src/k8s.io +git clone git@github.com:/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 +you want to be working from. + +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 +``` + +## 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

Concept Overviews

{% capture instructions %} -A concept overview covers the most essential, important information about core Kubernetes concepts and features. +A concept overview covers the most essential, important information about core +Kubernetes concepts and features. Examples of Concepts include `Pod`, +`Deployment`, `Service`, etc. -### Demos +### Example -- [Blank page that is trying to use template](blank/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/blank.md)) -- [Partially filled out page](partial/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/partial.md)) -- [Completely filled out page](filledout/) ([Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md)) +- [Source Link](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md) +- [Rendered Link](filledout/) ### Usage -To use this template, create a new file with these contents: +To create a new concept overview page, create a new file under +`docs/your-concept-name/index.md`. + +The file should start with the set of tags to apply to the concept and end +with an `include templates/concept-overview.md` block. + +The file needs to have the following `capture` sections: + +- concept +- when_to_use +- when_not_to_use +- status +- usage ```liquid{% raw %} --- +add +tags +here +e.g. +pod --- -{% capture concept %}{% endcapture %} -{% capture what_is %}{% endcapture %} -{% capture when_to_use %}{% endcapture %} -{% capture when_not_to_use %}{% endcapture %} -{% capture status %}{% endcapture %} -{% capture usage %}{% endcapture %} +{% 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 + +![Also add a diagram](/images/docs/file.svg){: style="max-width: 25%" } + +{% comment %} +Include a comment indicating where an editable image exists: +https://drive.google.com/open?id=1pQe4-s76fqyrzB8f3xoJo4MPLNVoBlsE1tT9MyLNINg +{% endcomment %} +{% endcapture %} + +{% 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. + +| Tables | Can Be | +|------------|----------------| +| Helpful | When | +| Comparing | Functionality | +| Across | Concepts | +{% endcapture %} + +{% capture when_not_to_use %} +Call out common anti-patterns to be avoided. +{% endcapture %} + +{% capture status %} +Describe how to get the current status of an instance in a cluster using kubectl + +Use a table to clarify the response. + +Consider status from kubectl describe as well. +{% endcapture %} + +{% 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. + +Include the example yaml here +{% endcapture %} + {% include templates/concept-overview.md %} -{% endraw %}``` +{% endraw %}``` ### Adding 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. +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. {% endcapture %} {{ instructions | markdownify }} @@ -70,7 +165,7 @@ A task page offers step-by-step instructions for completing a task with Kubernet ### Adding 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. +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. {% endcapture %} {{ instructions | markdownify }} @@ -106,7 +201,7 @@ cards: ### Adding page to navigation -Once your page is saved, somewhere in the `/docs/` directory, add a reference to the appropriate .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. +Once your page is saved, somewhere in the `/docs/` directory, add a reference to the appropriate .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 }} @@ -125,10 +220,10 @@ You probably shouldn't be using this, but we also have templates which consume Y ### Adding 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. +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. {% endcapture %} {{ instructions | markdownify }}
-
\ No newline at end of file +