ci: add docs related CI jobs

.github/.cspell/dart_dictionary.txt

@@ -0,0 +1,3 @@
+# Keywords/terms specific to the Dart/Flutter ecosystem
+dartdoc
+pubspec

.github/.cspell/globe_dictionary.txt

@@ -0,0 +1 @@
+# Dictionary file for Globe-related words

.github/.cspell/people_usernames.txt

@@ -0,0 +1 @@
+# Specific people's names and/or usernames

.github/.cspell/words_dictionary.txt

@@ -0,0 +1 @@
+# Actual english words (or common abbreviations) missing from CSpell

.github/cspell.json

@@ -0,0 +1,44 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "flagWords": [
+    "teh",
+    "hte"
+  ],
+  "ignorePaths": [
+    "**/CHANGELOG.md"
+  ],
+  "ignoreRegExpList": [
+    "\\#[\\w\\-]+"
+  ],
+  "dictionaries": [
+    "en_US",
+    "softwareTerms",
+    "dart_dictionary",
+    "globe_dictionary",
+    "people_usernames",
+    "words_dictionary"
+  ],
+  "dictionaryDefinitions": [
+    {
+      "name": "dart_dictionary",
+      "path": "./.cspell/dart_dictionary.txt",
+      "addWords": true
+    },
+    {
+      "name": "globe_dictionary",
+      "path": "./.cspell/globe_dictionary.txt",
+      "addWords": true
+    },
+    {
+      "name": "usernames",
+      "path": "./.cspell/people_usernames.txt",
+      "addWords": true
+    },
+    {
+      "name": "words_dictionary",
+      "path": "./.cspell/words_dictionary.txt",
+      "addWords": true
+    }
+  ]
+}

.github/workflows/dart_validate.yaml

@@ -2,7 +2,11 @@ name: all_dart_packages
 
 on:
   pull_request:
+    paths-ignore:
+      - 'docs/**'
   push:
+    paths-ignore:
+      - 'docs/**'
     branches:
       - main
 

.github/workflows/docs_comment.yaml

@@ -0,0 +1,19 @@
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "docs.yaml"
+    # types: [opened]
+
+jobs:
+  add_docs_link:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Comment PR
+        uses: thollander/actions-comment-pull-request@v2
+        with:
+          # pr number
+          message: |
+            :wave: Documentation changes in this PR can be previewed [here](https://docs.page/invertase/globe~${{ github.event.pull_request.number }}).

.github/workflows/spell_checker.yml

@@ -0,0 +1,16 @@
+name: spell_checker
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm -g install cspell
+      - run: ./scripts/cspell-run.sh
+      - run: ./scripts/cspell-verify.sh

scripts/cspell-run.sh

@@ -0,0 +1,3 @@
+#!/bin/bash -xe
+
+cspell --no-progress -c .github/cspell.json "**/*.{md,dart}"

scripts/cspell-verify.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+
+fix=$([[ "$*" == *--fix* ]] && echo true || echo false)
+
+function sort_fn() {
+    sort --ignore-case -C
+}
+
+function sort_dictionary() {
+    local file="$1"
+    local tmp_file=$(mktemp)
+
+    head -n 1 "$file" > "$tmp_file"
+    tail -n +2 "$file" | sort_fn >> "$tmp_file"
+    mv "$tmp_file" "$file"
+}
+
+function delete_unused() {
+    local file="$1"
+    local word="$2"
+
+    perl -i -ne "print unless /^\s*${word}\s*([# ].*)?$/i" "$file"
+}
+
+function lowercase() {
+    tr 'A-Z' 'a-z'
+}
+
+word_list="word_list.tmp"
+
+dictionary_dir=".github/.cspell"
+tmp_dir=".cspell.tmp"
+
+mv "$dictionary_dir" "$tmp_dir"
+mkdir "$dictionary_dir"
+for file in "$tmp_dir"/*; do
+    if [[ -f "$file" ]]; then
+        touch "$dictionary_dir/$(basename "$file")"
+    fi
+done
+cspell --dot --no-progress --unique --words-only "**/*.{md,dart}" | lowercase | sort -f > $word_list  || exit 1
+rm -r "$dictionary_dir"
+mv "$tmp_dir" "$dictionary_dir"
+
+error=0
+for file in .github/.cspell/*.txt; do
+    echo "Processing dictionary '$file'..."
+
+    violation=$(awk '!/^#/' "$file" | sort_fn 2>&1 || true)
+    if [ -n "$violation" ]; then
+        echo "Error: The dictionary '$file' is not in alphabetical order. First violation: '$violation'" >&2
+        error=1
+        if $fix; then
+            echo "Fixing the dictionary '$file'"
+            sort_dictionary "$file"
+        fi
+    fi
+
+    while IFS= read -r line; do
+        # split the line by # to remove comments
+        word=$(echo "$line" | cut -d '#' -f 1 | xargs | lowercase) # xargs trims whitespace
+
+        # check if the word exists in the project
+        if [[ -n "$word" ]] && ! grep -wxF "$word" "$word_list" >/dev/null; then
+            echo "Error: The word '$word' in the dictionary '$file' is not needed." >&2
+            error=1
+            if $fix; then
+                echo "Fixing the dictionary '$file' with excess word $word"
+                delete_unused "$file" "$word"
+            fi
+        fi
+    done < "$file"
+done
+
+rm $word_list
+exit $error