From c934f7e947306ff45f10153407ff115a28053d9b Mon Sep 17 00:00:00 2001 From: Anthony Correa Date: Wed, 4 Feb 2026 17:42:54 -0600 Subject: [PATCH] ci, build, release --- .github/workflows/ci-docs.yml | 57 +++++++++++++++++ .github/workflows/release.yml | 114 ++++++++++++++++++++++++++++++++++ metadata.yml | 5 -- mkdocs/mkdocs.yml | 6 +- tools/build.sh | 2 +- 5 files changed, 177 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/ci-docs.yml create mode 100644 .github/workflows/release.yml delete mode 100644 metadata.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..9c3d8bd --- /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" + + 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" + zip -r "${GITHUB_REF_NAME}.zip" site_offline + + - 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/${{ 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