[glossary] Glossary MVP (#4865)

* [glossary] Glossary MVP

* resolve conflict

* initial pass at includable glossary data

* tag to term mapping

* Change StatefulSets to singular, StatefulSet

* revise glossary style guide, move

* make descriptions plural

Makefile

@@ -15,4 +15,4 @@ serve: ## Boot the development server.
 	jekyll serve
 
 stage: ## Run the Jekyll staging container.
-	docker run -ti --rm -v "$PWD":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.1
+	docker run -ti --rm -v "${PWD}":/k8sdocs -p 4000:4000 gcr.io/google-samples/k8sdocs:1.1

_data/canonical-tags.yml

@@ -0,0 +1,12 @@
+- Fundamental
+- API Object
+- Metadata
+- Configuration
+- Security
+- Networking
+- Storage
+- Operation
+- Workload
+- Component
+- API
+- Extension

_data/canonical-terms-tags.yml

@@ -1,30 +0,0 @@
-canonical-tags:
-- Fundamental
-- API Object
-- Metadata
-- Configuration
-- Security
-- Networking
-- Storage
-- Operation
-- Workload
-- Component
-- API
-- Extension
-
-# TODO: Add list of glossary terms here
-# (to avoid writing a function that iterates through all glossary term pages)
-# e.g.
-# terms:
-# - name: StatefulSets
-#   tags:
-#   - Storage
-#   - Workload
-#   - API Object
-# - name: Aggregation Layer
-#   tags:
-#   - API
-#   - Component
-#   - Extension
-#
-# See https://github.com/kubernetes/kubernetes.github.io/projects/4 for details.

_data/glossary/_example.yml

@@ -0,0 +1,17 @@
+id: _example
+name: Example K8s Term
+formerly:
+- Slang K8s Term
+- Misnomer
+- Formerly Known as Prince
+related:
+- Less Fancy K8s Term
+- Tangential Term
+- Commonly Used With
+tags:
+- Some Tag
+short-description: |
+  Required. One or two lines that provide a minimum definition. Do not repeat the term. Write about the plural of the term. Prefer fragments. Model after tooltips. End with a period.
+long-description: |
+  Optional. Longer additional text to appear after (in conjunction with) short description. Provide where the short description is not sufficient as the intro paragraph to a topic. Write complete but concise sentences.
+  **See /_includes/templates/glossary/README.md for the official style guide.**

_data/glossary/statefulset.yml

@@ -0,0 +1,18 @@
+id: statefulset
+name: StatefulSet
+formerly:
+- PetSet
+related:
+- Deployment
+- Pod
+tags:
+- Storage
+- Workload
+- API Object
+short-description: |
+  Manage the deployment and scaling of a set of Pods, *and provide guarantees about ordering*. They do so by maintaining a *unique*, sticky identity for each of their Pods.
+
+long-description: |
+  Like Deployments, StatefulSets manage Pods that are based on an identical container spec. However, although their specs are the same, the Pods in a StatefulSet are not interchangeable. Each Pod has a persistent identifier that it maintains across any rescheduling.
+
+  StatefulSets also operate according to the Controller pattern. You define your desired state in a StatefulSet *object*, and the StatefulSet *controller* makes any necessary updates to the get there from the current state.

_includes/glossary/_glossary-template.md

@@ -1,24 +0,0 @@
-
----
-term: Some Fancy K8s Term
-formerly:
-- Slang K8s Term
-- Misnomer
-- Formerly Known as Prince
-related:
-- Less Fancy K8s Term
-- Tangential Term
-- Commonly Used With
----
-
-{% capture short-description %}
-Required. One or two lines that provide a minimum definition. Do not repeat the term. Prefer fragments. Model after tooltips.
-{% endcapture %}
-
-{% capture long-description %}
-Optional. Longer additional text to appear after (in conjunction with) short description. Provide where the short description is not sufficient as the intro paragraph to a topic. Write complete but concise sentences.
-
-Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed hendrerit dictum nisi quis posuere. Integer eleifend neque lobortis ultrices viverra. Praesent viverra placerat ex sit amet aliquet. Aliquam non ipsum ut lectus viverra pulvinar id vitae nisi. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Suspendisse aliquet congue tristique. Pellentesque at condimentum orci, iaculis pellentesque urna. Aliquam ut rhoncus lorem, a tristique est. Quisque eu est sem.
-
-Suspendisse id feugiat orci. Etiam in posuere arcu, id euismod velit. Etiam pulvinar lectus at diam porta, non lobortis dolor blandit. Donec id faucibus elit. Suspendisse auctor ligula purus, id aliquam odio vehicula a. Donec pretium ligula at nulla pulvinar, sed ultrices ligula dapibus. Cras lacinia mauris ut metus rutrum volutpat. Sed fermentum lobortis ipsum, in hendrerit lectus consectetur sed. Aliquam pulvinar tortor tellus, ac luctus est euismod congue. Maecenas enim ipsum, maximus a turpis eu, blandit imperdiet lacus.
-{% endcapture %}

_includes/tag-map.md

@@ -0,0 +1,15 @@
+<!-- Use include_cached when incorporating this file, in order to reduce computation/build time -->
+
+{% assign glossary_terms = site.data.glossary | where_exp: "term", "term.id != '_example'" %}
+
+{% assign tag_map = "" | split: " " %}
+
+{% for tag in site.data.canonical-tags %}
+
+{% assign term_list = glossary_terms | where_exp:"term", "term.tags contains tag" | map: "id" %}
+
+{% assign tag_obj = "" | split: " " | push: tag | push: term_list %}
+
+{% assign tag_map = tag_map | push: tag_obj %}
+
+{% endfor %}

_includes/templates/glossary/README.md

@@ -0,0 +1,62 @@
+# Kubernetes Glossary
+
+To write a glossary snippet, start with a copy of the template, [`/_data/glossary/_example.yml`](/_data/glossary/_example.yml). Make sure to provide (or omit) values for the following fields:
+
+* (Required) `id`.
+  * This field must match the name of the glossary file itself (without the `*.yml` extension). It is *not* intended to be displayed to users, and is only used programmatically.
+* (Required) `name`.
+  * The name of the term.
+* (Required) `tags`.
+  * Must be one of the tags listed in kubernetes.github.io/_data/canonical-terms-tags.yml.
+* (Required) `short description`.
+  * Make sure to replace the instructional text in the template with your content.
+* (Optional) `formerly` and `related`.
+  * If you do not provide these values, remove the fields.
+* (Optional) `long description`.
+  * If you do not provide a long description, remove the field -- that is, the complete key-value pair.
+
+The `_example.yml` template also contains basic information about how to write your snippet. For additional guidance, continue reading this readme.
+
+## Glossary snippet style guide
+
+This style guide supplements the guidance provided in the glossary template. It's intended to help you think about what and how to write glossary definitions. For more general guidance on style, consult [the core docs style guide](https://kubernetes.io/docs/home/contribute/style-guide/).
+
+### Minimum viable snippet:
+
+Every snippet must include at least the short description. The long description is optional, but should be provided for terms that need additional clarification. For consistency with existing *Concept* definitions, *write your definitions as if the term is plural*.
+
+**short-description** (Required): One line (or two short lines) that provides a minimum definition. Do not repeat the term. Prefer fragments. Model after tooltips. End with a period.
+
+**long-description** (Optional): Longer additional text to appear after (in conjunction with) short description. Provide in cases where the short description is not sufficient for the intro paragraph to a topic. Write complete but concise sentences.
+
+### Examples
+
+```yaml
+- name: Pod
+- tags:
+  - Fundamental
+  - Workload
+  - API Object
+- short-description: The smallest and simplest Kubernetes objects. Represent a set of running processes on your cluster.
+- long-description: Pods most often run only a single container, and are managed by a Deployment.
+```
+
+```yaml
+- name: Deployment
+- tags:
+  - Fundamental
+  - Workload
+  - API Object
+- short-description: Controllers that provide declarative updates for Pods and ReplicaSets.
+- long-description: Deployments are responsible for creating and updating instances of an application.
+```
+
+### Thinking about definitions
+
+* **Think of the short description as it would appear in a tooltip.** Is it sufficient to get the reader started? Is it short enough to be read inside a small UI element?
+
+  *Tip*: look at the API reference doc content (for example, https://kubernetes.io/docs/api-reference/v1.7/). Note, however, that this content should be used with care. The concept docs for Pod, for example, are clearer than the reference docs.
+
+* **The long description should follow the short description to make a complete introduction to a topic.** (This is the content that appears at the top of the content, before any generated TOC.) Does it provide information that's not already clear from the short description? Does it provide information that readers should have a general sense of before they dive into the details of the topic it helps introduce?
+
+  *Tip:* the long description does not need to be long; it's intended to extend but not replace the short description. Look through current related docs for ideas. (The Deployment long description is taken from a tutorial, for example.)

_includes/templates/glossary/_error.md

@@ -0,0 +1,10 @@
+### ERROR: You must define a <span style="font-family: monospace">`{{ include.missing_block }}`</span> field
+{: style="color:red" }
+
+The glossary template requires that you provide text that {{ include.purpose }}.
+
+To get rid of this message and take advantage of this template, define the `{{ include.missing_block }}`
+field for the `{{ include.term }}` glossary term and populate it with content.
+
+See `_data/glossary/_example.yml` for reference.
+<!-- TEMPLATE_ERROR -->

_includes/templates/glossary/snippet.md

@@ -0,0 +1,25 @@
+{% assign term_data = site.data.glossary.[include.term] %}
+
+{% if term_data.short-description %}
+
+{{ term_data.short-description | markdownify }}
+
+{% else %}
+
+{% include templates/glossary/_error.md term=term_data.name missing_block='short-description' purpose='concisely describes the key term in 1-2 lines' %}
+
+{% endif %}
+
+{% if include.length == "long" %}
+
+{% if term_data.long-description %}
+
+{{ term_data.long-description | markdownify }}
+
+{% else %}
+
+{% include templates/glossary/_error.md term=term_data.name missing_block='long-description' purpose='describes the key term in greater depth, supplementing the short-description' %}
+
+{% endif %}
+
+{% endif %}

docs/concepts/workloads/controllers/statefulset.md

@@ -15,8 +15,7 @@ PetSets feature from 1.4. Users of PetSets are referred to the 1.5
 [Upgrade Guide](/docs/tasks/manage-stateful-set/upgrade-pet-set-to-stateful-set/)
 for further information on how to upgrade existing PetSets to StatefulSets.**
 
-A StatefulSet is a Controller that provides a unique identity to its Pods. It provides
-guarantees about the ordering of deployment and scaling.
+{% include templates/glossary/snippet.md term="statefulset" length="long" %}
 {% endcapture %}
 
 {% capture body %}
@@ -40,6 +39,7 @@ provides a set of stateless replicas. Controllers such as
 [ReplicaSet](/docs/concepts/workloads/controllers/replicaset/) may be better suited to your stateless needs.
 
 ## Limitations
+
 * StatefulSet is a beta resource, not available in any Kubernetes release prior to 1.5.
 * As with all alpha/beta resources, you can disable StatefulSet through the `--runtime-config` option passed to the apiserver.
 * The storage for a given Pod must either be provisioned by a [PersistentVolume Provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin.

test/glossary_test.go

@@ -0,0 +1,91 @@
+/*
+Copyright 2016 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package examples_test
+
+import (
+  "io/ioutil"
+  "gopkg.in/yaml.v2"
+  "path"
+  "strings"
+	"testing"
+)
+
+// Not unmarshaling short-description and long-description fields
+// (for simplicity)
+type GlossaryTerm struct {
+  Id string          `yaml: "id"`
+  Name string        `yaml: "name"`
+  Formerly []string  `yaml: "formerly"`
+  Related []string   `yaml: "related"`
+  Tags []string      `yaml: "tags"`
+}
+
+// Checks that all glossary files (../_data/glossary/*) contain valid tags
+// that are present in the canonical set.
+func TestCanonicalTags(t *testing.T) {
+  canonicalTagsFile := "../_data/canonical-tags.yml"
+  data, err := ioutil.ReadFile(canonicalTagsFile)
+  if err != nil {
+    t.Errorf("Unable to read file %s: %v", canonicalTagsFile, err)
+    return
+  }
+  var tagList []string
+  err = yaml.Unmarshal(data, &tagList)
+  if err != nil {
+    t.Errorf("Unable to unmarshal file %s: %v", tagList, err)
+    return
+  }
+
+  canonicalTagsSet := make(map[string]bool)
+  for _, tag := range tagList {
+    canonicalTagsSet[tag] = true
+  }
+
+  glossaryDir := "../_data/glossary"
+  files, err := ioutil.ReadDir(glossaryDir)
+  if err != nil {
+    t.Errorf("Unable to read directory %s: %v", glossaryDir, err)
+    return
+  }
+
+  var term GlossaryTerm
+  for _, f := range files {
+    // skip validation of example files
+    if (strings.HasPrefix(f.Name(), "_")) {
+      continue
+    }
+
+    filePath := path.Join(glossaryDir, f.Name())
+    data, err := ioutil.ReadFile(filePath)
+    if err != nil {
+      t.Errorf("Unable to read file %s: %v", filePath, err)
+      continue
+    }
+    err = yaml.Unmarshal(data, &term)
+    if err != nil {
+      t.Errorf("Unable to unmarshal file %s: %v", filePath, err)
+      continue
+    }
+
+    for _, tag := range term.Tags {
+      if _, present := canonicalTagsSet[tag]; !present {
+        t.Errorf("Glossary term \"%s\" has invalid tag \"%s\". See %s for the list of valid tags.", term.Name, tag, canonicalTagsFile)
+        continue
+      }
+    }
+  }
+}