Merge pull request #12472 from keymanapp/feat/common/12347-check-mark…

…down-links

test(common): add markdown link check test for product documentation

android/build.sh

@@ -14,6 +14,7 @@ THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
 
 builder_describe \
   "Build Keyman Engine for Android, Keyman for Android, and FirstVoices Android app." \
+  "@/resources/tools/check-markdown  test:help" \
   clean \
   configure \
   build \
@@ -23,6 +24,7 @@ builder_describe \
   --upload-sentry+ \
   ":engine=KMEA                             Keyman Engine for Android" \
   ":app=KMAPro                              Keyman for Android" \
+  ":help                                    Online documentation" \
   ":sample1=Samples/KMSample1               Sample app: KMSample1" \
   ":sample2=Samples/KMSample2               Sample app: KMSample2" \
   ":keyboardharness=Tests/KeyboardHarness   Test app: KeyboardHarness" \
@@ -42,4 +44,7 @@ if builder_start_action clean; then
   builder_finish_action success clean
 fi
 
-builder_run_child_actions configure build test publish
+builder_run_child_actions configure build test
+builder_run_action        test:help    check-markdown  "$KEYMAN_ROOT/android/docs/help"
+
+builder_run_child_actions publish

developer/src/build.sh

@@ -11,6 +11,7 @@ THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
 
 builder_describe \
   "Keyman Developer" \
+  "@/resources/tools/check-markdown  test:help" \
   clean \
   configure \
   build \
@@ -20,6 +21,7 @@ builder_describe \
   "install                      Install built programs locally" \
   ":common                      Developer common files" \
   ":ext                         Third party components" \
+  ":help                        Online documentation" \
   ":kmcmplib                    Compiler - .kmn compiler" \
   ":kmc-analyze                 Compiler - Analysis Tools" \
   ":kmc-keyboard-info           Compiler - .keyboard_info Module" \
@@ -125,6 +127,7 @@ fi
 #-------------------------------------------------------------------------------------------------------------------
 
 builder_run_child_actions  clean configure build test
+builder_run_action         test:help    check-markdown  "$KEYMAN_ROOT/developer/docs/help"
 
 #-------------------------------------------------------------------------------------------------------------------
 

ios/build.sh

@@ -1,28 +1,27 @@
 #!/usr/bin/env bash
-
 ## START STANDARD BUILD SCRIPT INCLUDE
 # adjust relative paths as necessary
 THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
 . "${THIS_SCRIPT%/*}/../resources/build/builder.inc.sh"
 ## END STANDARD BUILD SCRIPT INCLUDE
 
-# Include our resource functions; they're pretty useful!
 . "$KEYMAN_ROOT/resources/shellHelperFunctions.sh"
 
-# Please note that this build script (understandably) assumes that it is running on Mac OS X.
-verify_on_mac
-
 builder_describe "Builds Keyman Engine and the Keyman app for use on iOS devices - iPhone and iPad." \
+  "@/resources/tools/check-markdown  test:help" \
   "clean" \
   "configure" \
   "build" \
+  "test" \
   ":engine                      Builds KeymanEngine.xcframework, usable by our main app and by third-party apps" \
   ":app=keyman                  Builds the Keyman app for iOS platforms" \
+  ":help                        Online documentation" \
   ":sample1=Samples/KMSample1   Builds the first KeymanEngine sample app" \
   ":sample2=Samples/KMSample2   Builds the second KeymanEngine sample app" \
   ":fv=../oem/firstvoices/ios   Builds OEM FirstVoices for iOS platforms" \
   "--sim-artifact+              Also outputs a simulator-friendly test artifact corresponding to the build"
 
 builder_parse "$@"
 
-builder_run_child_actions clean configure build
+builder_run_child_actions clean configure build test
+builder_run_action        test:help    check-markdown  "$KEYMAN_ROOT/ios/docs/help"

linux/build.sh

@@ -6,12 +6,16 @@ THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
 . "${THIS_SCRIPT%/*}/../resources/build/builder.inc.sh"
 ## END STANDARD BUILD SCRIPT INCLUDE
 
+. "$KEYMAN_ROOT/resources/shellHelperFunctions.sh"
+
 ################################ Main script ################################
 
 builder_describe \
   "Build Keyman for Linux." \
+  "@/resources/tools/check-markdown  test:help" \
   ":config=keyman-config             keyman-config" \
   ":engine=ibus-keyman               ibus-keyman" \
+  ":help                             Online documentation" \
   ":service=keyman-system-service    keyman-system-service" \
   "clean" \
   "configure" \
@@ -36,3 +40,4 @@ test_action() {
 }
 
 builder_run_action test test_action
+builder_run_action        test:help    check-markdown  "$KEYMAN_ROOT/linux/docs/help"

mac/build.sh

@@ -5,13 +5,13 @@ THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
 . "${THIS_SCRIPT%/*}/../resources/build/builder.inc.sh"
 ## END STANDARD BUILD SCRIPT INCLUDE
 
-# Include our resource functions; they're pretty useful!
 . "$KEYMAN_ROOT/resources/shellHelperFunctions.sh"
 . "$KEYMAN_ROOT/resources/build/build-help.inc.sh"
 . "$KEYMAN_ROOT/mac/mac-utils.inc.sh"
 
 builder_describe "Builds Keyman for macOS." \
   "@/core:mac" \
+  "@/resources/tools/check-markdown  test:help" \
   "clean" \
   "configure" \
   "build" \
@@ -20,12 +20,10 @@ builder_describe "Builds Keyman for macOS." \
   "install     Installs result of Keyman4MacIM locally." \
   ":engine     KeymanEngine4Mac" \
   ":app        Keyman4MacIM" \
+  ":help       Online documentation" \
   ":testapp    Keyman4Mac (test harness)" \
   "--quick,-q  Bypasses notarization for $(builder_term install)"
 
-# Please note that this build script (understandably) assumes that it is running on Mac OS X.
-verify_on_mac
-
 builder_parse "$@"
 
 # Default is release build of Engine and (code-signed) Input Method
@@ -89,8 +87,8 @@ UPLOAD_SENTRY=false
 
 # Import local environment variables for build
 #
-# /mac/localenv.sh can be used to define CERTIFICATE_ID, 
-# APPSTORECONNECT_PROVIDER, APPSTORECONNECT_USERNAME, 
+# /mac/localenv.sh can be used to define CERTIFICATE_ID,
+# APPSTORECONNECT_PROVIDER, APPSTORECONNECT_USERNAME,
 # APPSTORECONNECT_PASSWORD, DEVELOPMENT_TEAM variables;
 # see /mac/README.md for details.
 #
@@ -304,6 +302,7 @@ builder_run_action build:testapp  do_build_testapp
 
 builder_run_action test:engine    execBuildCommand $ENGINE_NAME "xcodebuild -project \"$KME4M_PROJECT_PATH\" $BUILD_OPTIONS test -scheme $ENGINE_NAME"
 builder_run_action test:app       execBuildCommand "$IM_NAME-tests" "xcodebuild test -workspace \"$KMIM_WORKSPACE_PATH\" $CODESIGNING_SUPPRESSION $BUILD_OPTIONS -scheme Keyman SYMROOT=\"$KM4MIM_BASE_PATH/build\""
+builder_run_action test:help      check-markdown  "$KEYMAN_ROOT/mac/docs/help"
 
 builder_run_action install do_install
 

package.json

@@ -32,6 +32,7 @@
   "scripts": {},
   "workspaces": [
     "resources/gosh",
+    "resources/tools/check-markdown",
     "resources/tools/strip-emoji",
     "resources/build/version",
     "core/include/ldml",

resources/shellHelperFunctions.sh

@@ -301,3 +301,7 @@ _select_node_version_with_nvm() {
     builder_die "Attempted to select node.js version $REQUIRED_NODE_VERSION but found $CURRENT_NODE_VERSION instead"
   fi
 }
+
+check-markdown() {
+  node "$KEYMAN_ROOT/resources/tools/check-markdown" --root "$1"
+}

resources/tools/check-markdown/.gitignore

@@ -0,0 +1 @@
+build/

resources/tools/check-markdown/README.md

@@ -0,0 +1,20 @@
+# check-markdown
+
+This tool is used to test the validity of internal links within product
+documentation, e.g. `/android/docs/help/**/*.md`.
+
+It currently tests that:
+
+1. Markdown can be parsed
+2. Links to other files in the same section exist (with or without .md extension)
+3. Images exist
+
+It will also optionally report on:
+
+1. External absolute links (starting with http/https)
+2. Relative links outside the root of the help documentation
+3. Unnecessary use of .md extension in links
+
+We could extend it to include:
+
+1. Checks for anchor validity

resources/tools/check-markdown/build.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+## START STANDARD BUILD SCRIPT INCLUDE
+# adjust relative paths as necessary
+THIS_SCRIPT="$(readlink -f "${BASH_SOURCE[0]}")"
+. "${THIS_SCRIPT%/*}/../../../resources/build/builder.inc.sh"
+## END STANDARD BUILD SCRIPT INCLUDE
+
+. "$KEYMAN_ROOT/resources/shellHelperFunctions.sh"
+
+################################ Main script ################################
+
+builder_describe "Check markdown internal links" \
+  "clean" \
+  "configure" \
+  "build"
+
+builder_describe_outputs \
+  configure          /node_modules \
+  build              build/index.js
+
+builder_parse "$@"
+
+builder_run_action clean      rm -rf build/ tsconfig.tsbuildinfo
+builder_run_action configure  verify_npm_setup
+builder_run_action build      tsc --build
+# builder_run_action test       mocha

resources/tools/check-markdown/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "check-markdown",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "build/index.js",
+  "license": "MIT",
+  "devDependencies": {
+    "marked": "^14.1.2",
+    "chalk": "^2.4.2"
+  }
+}