From 5f448b86fe058792fe06e7856cf1985ac55e13af Mon Sep 17 00:00:00 2001
From: John Mulhausen <johndylan@johndylan-macbookpro2.roam.corp.google.com>
Date: Sun, 26 Jun 2016 00:17:59 -0700
Subject: [PATCH] Refactor of template demo instructions

---
 _data/support.yml           |   2 +
 docs/sitemap.md             | 114 +++++++++++++++++++++++
 docs/templatedemos/index.md | 176 ++++++++++++++++++++----------------
 3 files changed, 215 insertions(+), 77 deletions(-)
 create mode 100644 docs/sitemap.md

diff --git a/_data/support.yml b/_data/support.yml
index 4ca3eeff0a..4ca3b339c8 100644
--- a/_data/support.yml
+++ b/_data/support.yml
@@ -40,3 +40,5 @@ toc:
     path: https://github.com/kubernetes/kubernetes/milestones/
   - title: Contributing to Kubernetes Documentation
     path: /editdocs/
+  - title: New Template Instructions
+    path: /docs/templatedemos/
diff --git a/docs/sitemap.md b/docs/sitemap.md
new file mode 100644
index 0000000000..a65bd4f01b
--- /dev/null
+++ b/docs/sitemap.md
@@ -0,0 +1,114 @@
+---
+---
+<script language="JavaScript">
+var dropDownsPopulated = false;
+$( document ).ready(function() {
+  // When the document loads, get the metadata JSON, and kick off tbl render
+  $.get("/metadata.txt", function(data, status) {
+    metadata = $.parseJSON(data);
+    metadata.pages.sort(dynamicSort("t"));
+    mainLogic()
+    $(window).bind( 'hashchange', function(e) {
+      mainLogic();
+    });
+  });
+});
+function mainLogic()
+{
+  // If there's a tag filter, change the table/drop down output
+  if (!dropDownsPopulated) populateDropdowns();
+  var tag=window.location.hash.replace("#","");
+  if(tag) {
+    tag = $.trim(tag);
+    for (i=0;i<tagName.length;i++) {
+      querystringTag = tagName[i] + "=";
+      if (tag.indexOf(querystringTag) > -1)
+      {
+        console.log("in mainLog: querystringTag of " + querystringTag + " matches tag of " + tag);
+        tag = tag.replace(querystringTag,"");
+        selectDropDown(tagName[i],tag);
+        topicsFilter(tagName[i],tag,"output");
+      }
+    }
+  } else {
+    currentTopics = metadata.pages;
+  }
+  renderTable(currentTopics,"output");
+
+}
+function populateDropdowns()
+{
+  // Keeping mainLogic() brief by functionizing the initialization of the
+  // drop-down filter boxes
+
+  for(i=0;i<metadata.pages.length;i++)
+  {
+    var metadataArrays = [metadata.pages[i].cr,metadata.pages[i].or,metadata.pages[i].mr];
+    for(j=0;j<metadataArrays.length;j++)
+    {
+      if (metadataArrays[j]) {
+        for (k=0;k<metadataArrays[j].length;k++) {
+          if (typeof storedTagsArrays[j] == 'undefined') storedTagsArrays[j] = new Array();
+          storedTagsArrays[j][metadataArrays[j][k][tagName[j]]] = true;
+          // ^ conceptList[metadata.pages[i].cr[k].concept] = true; (if rolling through concepts)
+          // ^ conceptList['container'] = true; (ultimate result)
+          // ^ objectList[metadata.pages[i].or[k].object] = true; (if rolling through objects)
+          // ^ objectList['restartPolicy'] = true; (ultimate result)
+        }
+      }
+    }
+  }
+  var output = new Array();
+  for(i=0;i<tagName.length;i++)
+  {
+    // Phew! All tags in conceptList, objectList, and commandList!
+    // Loop through them and populate those drop-downs through html() injection
+    output = [];
+    output.push("<select id='" + tagName[i] + "' onchange='dropFilter(this)'>");
+    output.push("<option>---</option>");
+    Object.keys(storedTagsArrays[i]).sort().forEach(function (key) {
+      output.push("<option>" + key + "</option>");
+    });
+    output.push("</select>")
+    $(dropDowns[i]).html(output.join(""));
+  }
+  dropDownsPopulated = true;
+}
+function dropFilter(srcobj)
+{
+  // process the change of a drop-down value
+  // the ID of the drop down is either command, object, or concept
+  // these exact values are what topicsFilter() expects, plus a filter val
+  // which we get from .text() of :selected
+  console.log("dropFilter:" + $(srcobj).attr('id') + ":" + $(srcobj).find(":selected").text());
+  topicsFilter($(srcobj).attr('id').replace("#",""),$(srcobj).find(":selected").text(),"output");
+  for(i=0;i<tagName.length;i++)
+  {
+    if($(srcobj).attr('id')!=tagName[i]) selectDropDown(tagName[i],"---");
+  }
+}
+function selectDropDown(type,tag)
+{
+  // change drop-down selection w/o filtering
+  $("#" + type).val(tag);
+}
+</script>
+<style>
+#filters select{
+  font-size: 14px;
+  border: 1px #000 solid;
+}
+#filters {
+  padding-top: 20px;
+}
+</style>
+
+Click tags or use the drop downs to filter. Click table headers to sort or reverse sort.
+
+<p id="filters">
+Filter by Concept: <span id="conceptFilter" /><br/>
+Filter by Object: <span id="objectFilter" /><br/>
+Filter by Command: <span id="commandFilter" />
+</p>
+
+<div id="output" />
diff --git a/docs/templatedemos/index.md b/docs/templatedemos/index.md
index bc63f807d9..bbb883fe9b 100644
--- a/docs/templatedemos/index.md
+++ b/docs/templatedemos/index.md
@@ -1,28 +1,28 @@
 ---
 ---
-<script>
-$(function() {
-    $( "#accordion" ).accordion();
-});
-</script>
 
-# Before you Begin: Get the docs code checked out locally
+* TOC
+{:toc}
+
+## 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
 
 ```shell
 cd ~/go/src/k8s.io
-git clone git@github.com:<you-github-repo>/kubernetes.github.io
+git clone git@github.com:<your-github-username>/kubernetes.github.io
 cd kubernetes.github.io
 git remote add upstream https://github.com/kubernetes/kubernetes.github.io.git
 ```
 
 ### 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.
 
@@ -38,9 +38,19 @@ git reset --hard upstream/docsv2
 
 - [Follow the editdocs instructions](http://kubernetes.io/editdocs/)
 
-# Writing Docs Using Templates
+Or, just use Docker! Run this from within your `kubernetes.github.io` directory and you should be good:
+
+```shell
+docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 johndmulhausen/k8sdocs
+```
+
+The site will then be viewable at [http://localhost:4000/](http://localhost:4000/).
+
+
+## Writing Docs Using Templates
+
+### Types of Templates
 
-## Types of Templates
 - Concept Template
   - Introduce K8s Api Objects e.g. Pod
 - Task Template
@@ -50,19 +60,18 @@ git reset --hard upstream/docsv2
   - 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 %}
+## Concept Overview Template Details
 
 A concept overview covers the most essential, important information about core
 Kubernetes concepts and features.  Examples of Concepts include `Pod`,
 `Deployment`, `Service`, etc.
 
-## Reference Examples
+### Reference Examples
 
-- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/filledout.md)
-- [Link to Rendered Template](filledout/)
+- [Link to Example Template: Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/docsv2/docs/pod/index.md)
+- [Link to Example Template: Rendered](http://k8sdocs.github.io/docs/pod/)
 
-## Usage
+### Usage
 
 ### Creating the file
 
@@ -70,9 +79,12 @@ 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`.
 
+### 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.
+
 ### Adding the Template sections
 
-- tags
 - concept: the concept name e.g. Pod
 - what_is: one sentence description the function / role  of the concept.  Diagrams are helpful.
 - when_to_use: disambiguate when to use this vs alternatives
@@ -81,53 +93,66 @@ e.g. `docs/your-concept-name/index.md`.
 - usage: example yaml
 - template: include the template at the end
 
+### Tags structure
+
+- `object_rankings:` associates the page with API objects/functions.
+- `concept_rankings:` associates the page with Kubernetes concepts.
+- `command_rankings:` associates the page with CLI commands
+
+In each case, the association is ranked. If ranked "1," the topic will surface as a "Core Topic" (of high importance) on various associated pages. If ranked "2," the topic will be grouped under "Advanced Topics," which are deemed less essential.
+
+Only ranks 1 and 2 are supported.
+
+Tags are mandatory and should be thorough; they are the connective tissue of the site. To see them in action, [visit our sitemap](http://k8sdocs.github.io/docs/sitemap/).
+
+
 ```liquid{% raw %}
 ---
-objects:
-- list_of_concepts
-- fields_and_tools
-- that_are_the_focus
-concepts:
-- list_of_concepts: 10
-- fields_and_tools: 20
-- that_are_used: 30
-- with_a_sort_order: 15
-advanced: false
+glossary: A pod is the vehicle for running containers in Kubernetes.
+object_rankings:
+- object: pod
+  rank: 1
+concept_rankings:
+- concept: pod
+  rank: 1
+command_rankings:
+- command: kubect describe
+  rank: 1
+- command: kubectl get
+  rank: 1
 ---
 {% capture concept %} concept-name-here {% endcapture %}
 {% capture what_is %} description-of-concept-here {% endcapture %}
-{% capture when_to_use %} when-to-user-here {% endcapture %}
+{% capture when_to_use %} when-to-use-here {% endcapture %}
 {% capture when_not_to_use %} anti-patterns-here {% endcapture %}
 {% capture status %} how-to-get-with-kubectl-here {% endcapture %}
 {% capture usage %} yaml-config-usage-here {% endcapture %}
 {% include templates/concept-overview.md %}
 {% endraw %}```
 
-### 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.
-
-{% endcapture %}
-{{ instructions | markdownify }}
-
-</div>
-
-# Task Template Details
-<div>{% capture instructions %}
+## Task Template Details
 
 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.**
 
-## Example
-- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/task.md)
-- [Link to Rendered Page](task/)
+### Example
+
+- [Link to Example Template: Source](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/docsv2/docs/tasks/explicitly-scheduling-pod-node.md)
+- [Link to Example Template: Rendered](http://k8sdocs.github.io/docs/tasks/explicitly-scheduling-pod-node/)
 
 ### Usage
 
-## Creating the file
+### Creating the file
 
 To create a new task page, create a file under docs/tasks/task-name.
 e.g. `docs/tasks/your-task-name`.
 
+Task filenames should match the title, chaining words with dashes in all lowercase, omitting articles and prepositions. For example, the topic "Explictly Scheduling a Pod on a Node" is stored in file `/docs/tasks/explicitly-scheduling-pod-node.md`.
+
+### Adding the page to navigation
+
+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.
+
 ### Adding the Template sections
 
 - metadata: structured description of the doc content
@@ -136,19 +161,36 @@ e.g. `docs/tasks/your-task-name`.
 - set_by_step: Add multiple sections.  1 per step in the task.
 - template: include the template at the end
 
+### Tags structure
+
+- `object_rankings:` associates the page with API objects/functions.
+- `concept_rankings:` associates the page with Kubernetes concepts.
+- `command_rankings:` associates the page with CLI commands
+
+In each case, the association is ranked. If ranked "1," the topic will surface as a "Core Topic" (of high importance) on various associated pages. If ranked "2," the topic will be grouped under "Advanced Topics," which are deemed less essential.
+
+Only ranks 1 and 2 are supported.
+
+Tags are mandatory and should be thorough; they are the connective tissue of the site. To see them in action, [visit our sitemap](http://k8sdocs.github.io/docs/sitemap/).
+
+
 ```liquid{% raw %}
 ---
-synopsis: "one sentence description of task."
-objects:
-- list_of_concepts
-- fields_and_tools
-- that_are_the_focus
-concepts:
-- list_of_concepts: 10
-- fields_and_tools: 20
-- that_are_used: 30
-- with_a_sort_order: 15
-advanced: false
+object_rankings:
+- object: nodeAffinity
+  rank: 1
+- object: nodeSelector
+  rank: 2
+concept_rankings:
+- concept: node
+  rank: 1
+- concept: pod
+  rank: 1
+command_rankings:
+- command: kubectl label
+  rank: 1
+- command: kubectl get
+  rank: 2
 ---
 {% capture purpose %} task-description-here {% endcapture %}
 {% capture recommended_background %} prereq-reading-here {% endcapture %}
@@ -156,17 +198,8 @@ advanced: false
 {% include templates/task.md %}
 {% endraw %}```
 
-### Adding the page to navigation
 
-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>
-
-# Landing Pages
-<div>{% capture instructions %}
+## Landing Pages
 
 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.
 
@@ -196,27 +229,16 @@ cards:
 
 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 }}
 
-</div>
+## kubectl yaml
 
-
-# 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
 
-- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/templatedemos/kubectl.md)
-- [Link to Rendered Template](kubectl/)
+- [Link to Example Template](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/docsv2/docs/kubectl/kubectl_api-versions.md)
+- [Link to Rendered Template](http://k8sdocs.github.io/docs/kubectl/kubectl_api-versions/)
 
 ### 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.
-
-{% endcapture %}
-{{ instructions | markdownify }}
-
-</div>
-</div>
+Once your page is saved, somewhere in the `/docs/` directory, add a reference to the `reference.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.
\ No newline at end of file