Introduce a check links source files with documentation about them. (#307)

Signed-off-by: Bill Farner <[email protected]>

Author: wfarner

Makefile

@@ -59,6 +59,7 @@ lint:
 check-docs:
 	@echo "+ $@"
 	find . -name '*.md' | grep -v vendor/ | blockcheck
+	./scripts/doc-source-check
 
 build:
 	@echo "+ $@"

README.md

@@ -25,7 +25,7 @@ environments while using shared components and consistent interfaces.
 _InfraKit_ makes extensive use of _Plugins_ to manage arbitrary systems in diverse environments, which can be composed
 to meet different needs.
 
-See the [plugins](docs/plugins.md) documentation for more details.
+See the [plugins](docs/plugins) documentation for more details.
 
 
 ## Building

docs/plugins.md renamed to docs/plugins/README.md

@@ -0,0 +1,5 @@
+# Instance plugin
+
+<!-- SOURCE-CHECKSUM pkg/spi/instance/* 0c778e96cbeb32043532709412e15e6cc86778d7153c65b1d7422b9f0b5901c89362666bfdd75de7 -->
+
+## API

docs/plugins/instance.md

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+# Validate that documentation is kept up to date with the sources being documented.
+#
+# This is a low-tech approach to ensure that documentation is validated when relevant sources
+# are changed.  A markdown file can 'call out' the sources being referenced using an HTML comment.
+# For example:
+#
+#   <!-- SOURCE-CHECKSUM pkg/spi/instance/* ABCDEF -->
+#
+# This instructs the script to compute a checksum of the files under pkg/spi/instance and check
+# that it matches ABCDEF.
+#
+# The goal is to remind developers to update documentation when code changes.  Hashing the source
+# files undoubtedly raises false positives, but mitigates stale documentation.
+
+set -o errexit
+set -o nounset
+
+HERE="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$HERE/.."
+
+# Check all markdown files we own.
+for f in $(find . -name '*.md' -not -path './vendor/*')
+do
+  # Look for the sentinel string.
+  doc_source_link=$(grep '<!-- SOURCE-CHECKSUM' "$f" || true)
+  if [ "$doc_source_link" == "" ]
+  then
+    continue
+  fi
+
+  echo -n "Validating source checksum in $f: "
+
+  # Split the command arguments.
+  IFS=' ' read -r -a link_cmd <<< "$doc_source_link"
+  if [ "${link_cmd[1]}" != "SOURCE-CHECKSUM" -o "${#link_cmd[@]}" -lt 5 ]
+  then
+    echo "FAIL"
+    echo "Invalid SOURCE-CHECKSUM command"
+    echo "<!-- SOURCE-CHECKSUM file-pattern checksum -->"
+    exit 1
+  fi
+
+  file_pattern="${link_cmd[2]}"
+  checksum="${link_cmd[3]}"
+
+  # Use git to hash the source files specified, concatenating them to form a single hash string.
+  hash=$(git hash-object $file_pattern | tr -d '\n')
+  if [ "$hash" == "$checksum" ]
+  then
+    echo "PASS"
+  else
+    echo "FAIL"
+    echo "Expected: $checksum"
+    echo "Actual: $hash"
+    exit 1
+  fi
+done