Make spell checking and style checking part of our doc checkin gate. (#1154)

.circleci/config.yml

@@ -17,28 +17,48 @@ jobs:
       # Download and cache dependencies
       - restore_cache:
           keys:
-          - v3-dependencies-{{ checksum "Gemfile.lock" }}
+          - v4-dependencies-{{ checksum "Gemfile.lock" }}
           # fallback to using the latest cache if no exact match is found
-          - v3-dependencies-
+          - v4-dependencies-
 
       - run:
-          name: install dependencies
+          name: Installing proofer dependencies
           command: |
             gem install bundler
-            bundle install --jobs=4 --retry=3 --path vendor/bundle
+            bundle install --jobs=4 --retry=3 --path .vendor/bundle
 
       - save_cache:
           paths:
-            - ./vendor/bundle
-          key: v3-dependencies-{{ checksum "Gemfile.lock" }}
+            - ./.vendor/bundle
+          key: v4-dependencies-{{ checksum "Gemfile.lock" }}
 
       - restore_cache:
           keys:
           - htmlproofer-cache-v3
-      # Run the test/html checker
-      - run: bundle exec rake test
+
+      - run:
+          name: Proofing HTML
+          command:
+            bundle exec rake test
+
       # save the external URLs cache
       - save_cache:
           key: htmlproofer-cache-v3
           paths:
             - tmp/.htmlproofer
+
+      - run:
+          name: Installing speller dependencies
+          command: |
+            mkdir -p .vendor/node
+            npm install --prefix .vendor/node markdown-spellcheck
+
+      - run:
+          name: Checking markdown spelling
+          command:
+            .vendor/node/node_modules/markdown-spellcheck/bin/mdspell --en-us --ignore-acronyms --ignore-numbers --no-suggestions --report *.md */*.md */*/*.md */*/*/*.md */*/*/*/*.md
+
+      - run:
+          name: Checking markdown style
+          command:
+            mdl --ignore-front-matter --style mdl_style.rb .

Gemfile

@@ -5,3 +5,4 @@ gem "jekyll-include-cache", "~> 0.1"
 gem "nokogiri", ">= 1.8.1"
 gem "html-proofer", ">= 3.8.0"
 gem "rake"
+gem "mdl"

Gemfile.lock

@@ -210,6 +210,10 @@ GEM
       rb-fsevent (~> 0.9, >= 0.9.4)
       rb-inotify (~> 0.9, >= 0.9.7)
       ruby_dep (~> 1.2)
+    mdl (0.4.0)
+      kramdown (~> 1.12, >= 1.12.0)
+      mixlib-cli (~> 1.7, >= 1.7.0)
+      mixlib-config (~> 2.2, >= 2.2.1)
     mercenary (0.3.6)
     mini_portile2 (2.3.0)
     minima (2.4.0)
@@ -217,6 +221,9 @@ GEM
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
     minitest (5.11.3)
+    mixlib-cli (1.7.0)
+    mixlib-config (2.2.6)
+      tomlrb
     multipart-post (2.0.0)
     net-dns (0.8.0)
     nokogiri (1.8.2)
@@ -248,6 +255,7 @@ GEM
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     thread_safe (0.3.6)
+    tomlrb (1.2.6)
     typhoeus (1.3.0)
       ethon (>= 0.9.0)
     tzinfo (1.2.5)
@@ -262,6 +270,7 @@ DEPENDENCIES
   github-pages
   html-proofer (>= 3.8.0)
   jekyll-include-cache (~> 0.1)
+  mdl
   nokogiri (>= 1.8.1)
   rake
 

README.md

@@ -9,6 +9,7 @@ contribute to any of the Istio components, please
 see the Istio [contribution guidelines](https://github.com/istio/community/blob/master/CONTRIBUTING.md).
 
 * [Working with the site](#building-the-site)
+* [Linting](#linting)
 * [Versions and releases](#versions-and-releases)
   * [How versioning works](#how-versioning-works)
   * [Creating a version](#creating-a-version)
@@ -59,6 +60,18 @@ bundle exec rake test
 bundle exec jekyll serve
 ```
 
+## Linting
+
+You should run `scripts/linters.sh` prior to checking in your changes.
+This will run 3 tests:
+
+- HTML proofing, which ensures all your links are valid along with other checks.
+
+- Spell checking. If errors are reported, you either need to correct the errors, or add new works to the
+exception dictionary which is in the file `./.spelling`.
+
+- Style checking, which makes sure your markdown file complies with some common style rules.
+
 ## Versions and releases
 
 Istio maintains three variations of its public website:

_layouts/docs.html

@@ -4,7 +4,7 @@ layout: default
 <div class="container-fluid">
     <div class="row row-offcanvas row-offcanvas-left">
         <div class="col-6 col-md-3 col-xl-2 sidebar-offcanvas">
-            {% include sidebar.html docs=site.blog %}
+            {% include sidebar.html docs=site.docs %}
         </div>
 
         {% assign needTOC = true %}

scripts/linters.sh

@@ -1,3 +1,10 @@
+#! /bin/sh
+# This script will spell check all markdown files in the repo,
+# while style check those files, and finally will proof the
+# final HTML looking for broken links and other common errors.
+set -x
+set -e
+
 mdspell --en-us --ignore-acronyms --ignore-numbers --no-suggestions --report *.md */*.md */*/*.md */*/*/*.md */*/*/*/*.md
 mdl --ignore-front-matter --style mdl_style.rb .
-rake test
+bundle exec rake test