From f59d056cf46318a22a1bfd5c55a3961e854644b9 Mon Sep 17 00:00:00 2001 From: Anthony Correa Date: Wed, 4 Feb 2026 17:42:54 -0600 Subject: [PATCH] ci, build, release + update spellcheck to use cspell --- .github/workflows/ci-docs.yml | 57 +++++++++ .github/workflows/release.yml | 114 +++++++++++++++++ metadata.yml | 5 - mkdocs/mkdocs.yml | 6 +- tools/build.sh | 2 +- tools/spell-check/.aspell.en.prepl | 1 - tools/spell-check/.aspell.en.pws | 22 ---- tools/spell-check/git-spell-check | 189 ---------------------------- tools/spell-check/spell-check | 10 -- tools/spellcheck/baseball-words.txt | 5 + tools/spellcheck/cspell.yml | 25 ++++ 11 files changed, 207 insertions(+), 229 deletions(-) create mode 100644 .github/workflows/ci-docs.yml create mode 100644 .github/workflows/release.yml delete mode 100644 metadata.yml delete mode 100644 tools/spell-check/.aspell.en.prepl delete mode 100644 tools/spell-check/.aspell.en.pws delete mode 100755 tools/spell-check/git-spell-check delete mode 100755 tools/spell-check/spell-check create mode 100644 tools/spellcheck/baseball-words.txt create mode 100644 tools/spellcheck/cspell.yml diff --git a/.github/workflows/ci-docs.yml b/.github/workflows/ci-docs.yml new file mode 100644 index 0000000..95695e8 --- /dev/null +++ b/.github/workflows/ci-docs.yml @@ -0,0 +1,57 @@ +name: CI - Docs build check + +on: + push: + branches: + - main + - develop + - release-candidate + workflow_dispatch: + +permissions: + contents: read + +env: + MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }} + MKDOCS_CONFIG: mkdocs/mkdocs.yml + MKDOCS_OFFLINE: false + CSPELL_CONFIG: tools/spellcheck/cspell.yml + CSPELL_TARGETS: docs/**/*.md README.md + +jobs: + build-check: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Spellcheck + run: | + set -euo pipefail + npx --yes cspell \ + --config ${CSPELL_CONFIG} \ + ${CSPELL_TARGETS} + + - name: Install build dependencies + run: | + set -euo pipefail + pip install -r mkdocs/requirements.txt + + - name: MkDocs build (strict default) + + run: | + set -euo pipefail + echo "Strict is set to ${MKDOCS_STRICT}" + FLAGS=() + + if [ "${MKDOCS_STRICT}" = "true" ]; then + FLAGS+=(--strict) + fi + MKDOCS_OUTPUT_DIR="${RUNNER_TEMP:-${TMPDIR:-/tmp}}/dist" + + mkdocs build "${FLAGS[@]}" -f "${MKDOCS_CONFIG}" -d "${MKDOCS_OUTPUT_DIR}" \ No newline at end of file diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..c56c61c --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,114 @@ +name: Build & publish docs (rc + release) + +on: + push: + tags: + - "rc*" + - "v*" + workflow_dispatch: + +permissions: + contents: write + +env: + MKDOCS_CONFIG: mkdocs/mkdocs.yml + MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT || 'true' }} + +jobs: + publish: + runs-on: ubuntu-latest + + steps: + - name: Checkout (tag) + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install deps + run: | + set -euo pipefail + pip install -r mkdocs/requirements.txt + + - name: Build docs (normal + offline, strict gate) + run: | + set -euo pipefail + + FLAGS=() + if [ "${MKDOCS_STRICT}" = "true" ]; then + FLAGS+=(--strict) + fi + + OUT_BASE="${RUNNER_TEMP}/mkdocs_out" + SITE="${OUT_BASE}/site" + SITE_OFFLINE="${OUT_BASE}/site_offline/${GITHUB_REF_NAME}" + + rm -rf "${OUT_BASE}" + mkdir -p "${SITE}" "${SITE_OFFLINE}" + + mkdocs build "${FLAGS[@]}" -f "${MKDOCS_CONFIG}" -d "${SITE}" + OFFLINE=true mkdocs build "${FLAGS[@]}" -f "${MKDOCS_CONFIG}" -d "${SITE_OFFLINE}" + + - name: Zip offline site + run: | + set -euo pipefail + cd "${RUNNER_TEMP}/mkdocs_out/site_offline/" + zip -r "${GITHUB_REF_NAME}.zip" ./${GITHUB_REF_NAME} + + - name: Publish prerelease + if: startsWith(github.ref_name, 'rc') + uses: softprops/action-gh-release@v2 + with: + prerelease: true + name: ${{ github.ref_name }} + tag_name: ${{ github.ref_name }} + body: | + Release candidate preview (if deployed): /rc/ + files: | + ${{ runner.temp }}/mkdocs_out/${{ github.ref_name }}.zip + + - name: Publish release + if: startsWith(github.ref_name, 'v') + uses: softprops/action-gh-release@v2 + with: + name: ${{ github.ref_name }} + tag_name: ${{ github.ref_name }} + files: | + ${{ runner.temp }}/mkdocs_out/site_offline/${{ github.ref_name }}.zip + + - name: Checkout gh-pages branch + uses: actions/checkout@v4 + with: + ref: gh-pages + fetch-depth: 0 + + - name: Deploy release to gh-pages root + if: startsWith(github.ref_name, 'v') + run: | + set -euo pipefail + rm -rf ./* + cp -a ${RUNNER_TEMP}/mkdocs_out/site/. . + git add -A + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git commit -m "Deploy release ${GITHUB_REF_NAME}" || echo "No changes to commit" + git push origin gh-pages + + - name: Deploy RC preview to /rc/ + if: startsWith(github.ref_name, 'rc') + run: | + set -euo pipefail + rm -rf rc + mkdir -p rc + cp -a ${RUNNER_TEMP}/mkdocs_out/site/. rc/ + printf '{"tag":"%s"}\n' "${GITHUB_REF_NAME}" > rc/rc.json + + git add -A + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git commit -m "Deploy RC preview ${GITHUB_REF_NAME}" || echo "No changes to commit" + git push origin gh-pages \ No newline at end of file diff --git a/metadata.yml b/metadata.yml deleted file mode 100644 index efa2263..0000000 --- a/metadata.yml +++ /dev/null @@ -1,5 +0,0 @@ ---- - title: Chicago Metropolitan Baseball Association - subtitle: Constitution and By-Laws - date: 2024-06-06 ---- \ No newline at end of file diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 876465c..8f54999 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -36,4 +36,8 @@ plugins: - enumerate-headings: toc_depth: 2 exclude: - - index.md \ No newline at end of file + - index.md + +validation: + links: + anchors: warn #this defaults to info, but it will cause broken links in anchor headers \ No newline at end of file diff --git a/tools/build.sh b/tools/build.sh index b6b7917..6cf32f8 100755 --- a/tools/build.sh +++ b/tools/build.sh @@ -11,5 +11,5 @@ STRICT_FLAG="" if [ "${MKDOCS_STRICT}" = "true" ]; then STRICT_FLAG="--strict" fi - +echo "MKDOCS_STRICT: $MKDOCS_STRICT, STRICT_FLAG: $STRICT_FLAG" mkdocs build ${STRICT_FLAG} -f $MKDOCS_CONFIG -d $OUTPUT_DIR \ No newline at end of file diff --git a/tools/spell-check/.aspell.en.prepl b/tools/spell-check/.aspell.en.prepl deleted file mode 100644 index 4c3ecb8..0000000 --- a/tools/spell-check/.aspell.en.prepl +++ /dev/null @@ -1 +0,0 @@ -personal_repl-1.1 en 0 diff --git a/tools/spell-check/.aspell.en.pws b/tools/spell-check/.aspell.en.pws deleted file mode 100644 index e6e1bbb..0000000 --- a/tools/spell-check/.aspell.en.pws +++ /dev/null @@ -1,22 +0,0 @@ -personal_ws-1.1 en 19 -BBCOR -MLB -RO -Rawlings -chicagoland -cmba -cp -ePUB -epub -gh -gitdriver -github -html -jgm -lua -md -pandoc -repo -rostered -src -timeframe diff --git a/tools/spell-check/git-spell-check b/tools/spell-check/git-spell-check deleted file mode 100755 index 2ee3f32..0000000 --- a/tools/spell-check/git-spell-check +++ /dev/null @@ -1,189 +0,0 @@ -#!/bin/bash -# mprpic/git-spell-check -# https://github.com/mprpic/git-spell-check/ -set -e - -#adding this for use on a Mac -if command -v gsed &> /dev/null -then - sed=gsed -else - sed=sed -fi - -# Instructions: -# -# This script is a Git pre-commit hook that spell checks any content you are about to commit. -# -# Place this script into the ".git/hooks/" directory in your repository. It must be called "pre-commit" and be -# executable. A Git hook only works in a single repository. You need to copy this hook into every repository you wish to -# use it in manually. Optionally, you can set up a symlink in the ".git/hooks/" directory pointing to the script. -# -# Each time you try to commit something, this script is run and spell checks the content you are committing. -# -# Should you want to bypass the pre-commit hook (though not recommended), you can commit with "git commit --no-verify". - - -# The following is a text file that represents your custom dictionary; edit as necessary. Add words to it that you wish -# to ignore for the spell check. -dict=~/.git-spell-check -if [ ! -f $dict ]; then - touch ~/.git-spell-check - dict=~/.git-spell-check - printf "%s\n" "Custom dictionary not found. Created ~/.git-spell-check..." -fi - - -# The following is a temporary dictionary (a binary file) created from the dict text file. It is deleted after the -# script finishes. -temp_dict=$(mktemp docs-dictionary-XXXXXX) - -# Language of your doc. When using a non-English language, make sure you have the appropriate aspell libraries -# installed: "yum search aspell". For example, to spell check in Slovak, you must have the aspell-sk package installed. -lang=en - -# Define an extension for any additional dictionaries (containing words that are ignored during the spell check) that -# are kept locally in your repository. These dictionaries will be loaded on top of the existing global dictionary (by -# default ~/.git-spell-check). -extension=pws - -# Clean up if script is interrupted or terminated. -trap "cleanup" SIGINT SIGTERM - -# Prepares the dictionary from scratch in case new words were added since last time. -function prepare_dictionary() { - - local_dict=$(find . -name *.$extension -exec ls {} \;) - if [ -z "$local_dict" ]; then - sort -u $temp_dict -o $temp_dict - aspell --lang="$lang" create master "$temp_dict" < "$dict" - else - temp_file=$(mktemp temp_file-XXXXXX) - for file in $local_dict; do - cat $file >> $temp_file - done - cat $dict >> $temp_file - ## Remove header line - $sed -i '/personal_ws-/d' "${temp_file}" - sort -u $temp_file -o $temp_file - aspell --lang="$lang" create master "$temp_dict" < "$temp_file" - /bin/rm -f "$temp_file" - fi - -} - -# Removes the temporary dictionary. -function cleanup() { - - /bin/rm -f "$temp_dict" - -} - -# Spell checks content you're about to commit. Writes out words that are misspelled or exits with 0 (i.e. continues with -# commit). -function spell_check() { - - words=$(git diff --cached | grep -e "^+[^+]" | aspell --mode=sgml list --add-sgml-skip={ulink,code,literal,firstname,parameter,option,package,replaceable,programlisting,userinput,screen,filename,command,computeroutput,abbrev,accel,orgname,surname,foreignphrase,acronym,hardware,keycap,systemitem,application} --lang="$lang" --extra-dicts="$temp_dict" | sort -u) - if [ ! "$words" ]; then - printf "%s\n" "No typos found. Proceeding with commit..." - cleanup; exit 0 - fi - printf "%s\n" "Spell check failed on the following words: --------------------------------------------------" - echo $words - for word in $words; do - grep --color=always --exclude-dir={.git,tmp} -HIrone "\<$word\>" $(git diff --cached --name-only --diff-filter=ACMRTUXB) | awk -F ":" '{print "File: " $1 "\ton line: " $2 "\tTypo: " $3}' - printf "%s\n" "-------------------" - done - -} - -# Adds all, some, or none of the misspelled words to the custom dictionary. -function add_words_to_dict() { - - printf "%s\n" " -Add any of the misspelled words into your custom dictionary? - * a[ll] (add all words into dict, continue with commit) - * s[ome] (add some words into dict, fix others, no commit) - * i[gnore] (add some words into dict, ignore rest, continue with commit) - * n[one] (no commit) -" - - while true; do - exec < /dev/tty # Simply reading user input does not work because Git hooks have stdin detached. - read answer - shopt -s nocasematch - case "$answer" in - a|all) - add_all - cleanup; exit 0 - ;; - s|some) - add_some - printf "%s\n" "Please fix remaining typos, use \"git add\" to add fixed files, and commit." - cleanup; exit 1 - ;; - i|ignore) - add_some - cleanup; exit 0 - ;; - n|none) - add_none - cleanup; exit 1 - ;; - *) - printf "%s\n" "Incorrect answer. Try again." - continue - esac - shopt -u nocasematch - done - -} - -# Adds all words to the custom dictionary and continues with the commit. -function add_all() { - - for word in $words; do - echo $word >> "$dict" - done - -} - -# Adds some (selected by user) of the words to the dictionary and exits with 1. -function add_some() { - - for word in $words; do - printf "%s\n" "Do you want to add the following word to your custom dictionary: $word (y[es] or n[o])" - while true; do - exec < /dev/tty - read answer - shopt -s nocasematch - case "$answer" in - y|yes) - echo $word >> "$dict" - printf "%s\n" "\"$word\" added to your custom dictionary." - break ;; - n|no) - break ;; - *) - printf "%s\n" "Incorrect answer. Try again." - continue - esac - shopt -u nocasematch - done - done - -} - -# Adds none of the words and exits with 1. -function add_none() { - - printf "%s\n" "No words were added to your custom dictionary." - printf "%s\n" "Please fix remaining typos, use \"git add\" to add fixed files, and commit." - -} - - -prepare_dictionary -spell_check -add_words_to_dict \ No newline at end of file diff --git a/tools/spell-check/spell-check b/tools/spell-check/spell-check deleted file mode 100755 index ba705bc..0000000 --- a/tools/spell-check/spell-check +++ /dev/null @@ -1,10 +0,0 @@ -#!/bin/bash -set -e - -extension_files_to_check=md - -function spell_check(){ - find . -type f -name "*.${extension_files_to_check}" -exec aspell check {} --mode=markdown --home-dir=./.spell-check \; -} - -spell_check \ No newline at end of file diff --git a/tools/spellcheck/baseball-words.txt b/tools/spellcheck/baseball-words.txt new file mode 100644 index 0000000..2ff5e85 --- /dev/null +++ b/tools/spellcheck/baseball-words.txt @@ -0,0 +1,5 @@ +BBCOR +MLB +RO +Rawlings +rostered \ No newline at end of file diff --git a/tools/spellcheck/cspell.yml b/tools/spellcheck/cspell.yml new file mode 100644 index 0000000..3c23a09 --- /dev/null +++ b/tools/spellcheck/cspell.yml @@ -0,0 +1,25 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json + +# The version of the configuration file format. +version: "0.2" +# The locale to use when spell checking. (e.g., en, en-GB, de-DE +language: en-US +useGitignore: true +globRoot: "../.." +allowCompoundWords: true + +files: + - "**/*.md" + - ./README.md + +dictionaryDefinitions: + - name: baseball-words + path: ./baseball-words.txt + +dictionaries: + - baseball-words + +words: + - cmba + - chicagoland + - gitdriver \ No newline at end of file