Merge pull request #2151 from janetkuo/check-titles

Add script for checking titles

.travis.yml

@@ -14,4 +14,4 @@ install:
 script:
 - go test -v k8s.io/kubernetes.github.io/test
 - $GOPATH/bin/md-check --root-dir=$HOME/gopath/src/k8s.io/kubernetes.github.io
-- ./verify-entry-toc.sh
+- ./verify-docs-format.sh

docs/user-guide/walkthrough/index.md

@@ -2,7 +2,7 @@
 assignees:
 - eparis
 - mikedanese
-
+title: Kubernetes 101
 ---
 
 ## Kubectl CLI and Pods

docs/user-guide/walkthrough/k8s201.md

@@ -2,7 +2,7 @@
 assignees:
 - janetkuo
 - mikedanese
-
+title: Kubernetes 201
 ---
 
 ## Labels, Deployments, Services and Health Checking

skip_title_check.txt

@@ -0,0 +1,11 @@
+# Put files you want to skip "title:" check here:
+docs/sitemap.md
+docs/getting-started-guides/docker.md
+docs/user-guide/configmap/README.md
+docs/user-guide/downward-api/README.md
+docs/api-reference/extensions/v1beta1/definitions.md
+docs/api-reference/extensions/v1beta1/operations.md
+docs/api-reference/v1/definitions.md
+docs/api-reference/v1/operations.md
+docs/user-guide/pods/_viewing-a-pod.md
+docs/user-guide/simple-yaml.md

verify-docs-format.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+
+no_entry=false
+no_entry_counter=0
+no_title=false
+no_title_counter=0
+
+# Verify all docs/.../*.md files 
+# Skip checking autogenerated files in some folders
+# (docs/api-reference/1_5, docs/user-guide/kubectl/1_5, and
+# docs/resources-reference/1_5)
+for file in `find docs -name "*.md" -type f`; do 
+  # Skip checking all files in the following folders 
+  if [[ "${file}" == "docs/api-reference/1_"* ]] || 
+     [[ "${file}" == "docs/user-guide/kubectl/1_"* ]] ||
+     [[ "${file}" == "docs/resources-reference/1_"* ]]; then 
+    continue
+  fi 
+
+  # 1. TOC check:
+  #    Check they are referenced in at least one of _data/*.yml files.
+  #    Skip checking files in skip_toc_check.txt
+  if ! grep -q "${file}" skip_toc_check.txt; then
+    path=${file%.*}
+    # abc/index.md should point to abc, not abc/index
+    path=${path%%index}
+    if ! grep -q "${path}" _data/*.yml; then
+      echo "Error: ${file} doesn't have an entry in the table of contents under _data/*.yml" 
+      no_entry=true
+      no_entry_counter=$[no_entry_counter+1]
+    fi
+  fi
+
+  # 2. Title check:
+  #    Check they have a proper title.
+  #    Skip checking files in skip_title_check.txt.
+  #    Title should start with "title:" and can have several spaces/tabs between
+  #    non-space/tab content. They should also be inside the markdown header.
+  #    For example, "title:", " title: abc", and "title:" aren't valid, 
+  #    but "title: abc", "title:def" and "title:    def ghi" are both valid.
+  if [[ "${file}" == "docs/user-guide/kubectl/kubectl"* ]]; then 
+    # Skip checking auto-generated kubectl docs since its first heading matches title 
+    continue
+  fi 
+  if ! grep -q "${file}" skip_title_check.txt; then
+    if ! grep -q "^title:\s*[^\s]" ${file}; then 
+      echo "Error: ${file} doesn't have a proper title defined!"
+      no_title=true
+      no_title_counter=$[no_title_counter+1]
+    fi
+  fi
+done
+
+if ${no_entry}; then 
+  echo "Found ${no_entry_counter} files without entries. For how to fix it, see http://kubernetes.io/docs/contribute/write-new-topic/#creating-an-entry-in-the-table-of-contents"
+  exit 1
+fi
+
+if ${no_title}; then 
+  echo "Found ${no_title_counter} files without titles."
+  exit 1
+fi

verify-entry-toc.sh

@@ -1,22 +0,0 @@
-#!/bin/bash
-
-no_entry=false
-
-# Verify all docs/.../*.md files are referenced in at least one of _data/*.yml
-# files. Skip checking files in skip_toc_check.txt
-for file in `find docs -name "*.md" -type f`; do 
-  if ! grep -q "${file}" skip_toc_check.txt; then
-    path=${file%.*}
-    # abc/index.md should point to abc, not abc/index
-    path=${path%%index}
-    if ! grep -q "${path}" _data/*.yml; then
-      echo "Error: ${file} doesn't have an entry in the table of contents under _data/*.yml" 
-      no_entry=true
-    fi
-  fi
-done
-
-if ${no_entry}; then 
-  echo "Found files without entries. For how to fix it, see http://kubernetes.io/docs/contribute/write-new-topic/#creating-an-entry-in-the-table-of-contents"
-  exit 1
-fi