Add CALM json and generate mermaid and MD files for the architeture f… #26
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| # Copyright (c) 2025 Erick Bourgeois, firestoned | |
| # SPDX-License-Identifier: Apache-2.0 | |
| name: Documentation | |
| on: | |
| push: | |
| branches: | |
| - main | |
| paths: | |
| - 'docs/**' | |
| - 'src/**/*.rs' | |
| - '.github/workflows/docs.yaml' | |
| pull_request: | |
| paths: | |
| - 'docs/**' | |
| - 'src/**/*.rs' | |
| - '.github/workflows/docs.yaml' | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Allow one concurrent deployment; cancel any in-progress run on the same | |
| # branch so a rapid series of pushes never leaves a stale deploy running. | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: true | |
| env: | |
| CARGO_TERM_COLOR: always | |
| RUST_BACKTRACE: 1 | |
| # Override the cross-compilation linkers set in .cargo/config.toml. | |
| # On Linux CI runners the native target IS x86_64-unknown-linux-gnu so | |
| # cargo picks up the macOS cross-compiler setting — which isn't installed. | |
| CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: cc | |
| CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: cc | |
| jobs: | |
| # Validate the CALM architecture document before building the docs site. | |
| # Uses the reusable CALM workflow (see .github/workflows/CALM.md). | |
| # A broken architecture means broken diagrams downstream, so this is a | |
| # hard gate on every docs build. | |
| calm-validate: | |
| name: ✅ Validate CALM architecture | |
| uses: ./.github/workflows/calm.yaml | |
| with: | |
| command: validate | |
| architecture: docs/architecture/calm/architecture.json | |
| format: pretty | |
| verbose: true | |
| # Render one Mermaid flowchart per CALM flow into docs/src/architecture/. | |
| # The rendered markdown is uploaded as an artifact and consumed by the | |
| # build job below. The output directory is gitignored — the file only | |
| # exists at build time. | |
| calm-diagrams: | |
| name: 🧱 Render CALM Mermaid diagrams | |
| uses: ./.github/workflows/calm.yaml | |
| with: | |
| command: template | |
| architecture: docs/architecture/calm/architecture.json | |
| template-dir: docs/architecture/calm/templates/mermaid | |
| output: docs/src/architecture | |
| clear-output-directory: true | |
| verbose: true | |
| upload-artifact: true | |
| artifact-name: calm-mermaid | |
| artifact-retention-days: 7 | |
| build: | |
| name: 📚 Build Documentation | |
| needs: [calm-validate, calm-diagrams] | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 # Full history for git-revision-date-localized plugin | |
| - name: Download rendered CALM diagrams | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: calm-mermaid | |
| path: docs/src/architecture | |
| - name: Strip .hbs suffix from rendered files | |
| run: | | |
| set -euo pipefail | |
| shopt -s nullglob | |
| for f in docs/src/architecture/*.hbs; do | |
| mv "$f" "${f%.hbs}" | |
| done | |
| ls -la docs/src/architecture | |
| - name: Install Rust toolchain | |
| uses: dtolnay/rust-toolchain@stable | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.11' | |
| - name: Install Poetry | |
| run: | | |
| curl -sSL https://install.python-poetry.org | python3 - | |
| echo "$HOME/.local/bin" >> "$GITHUB_PATH" | |
| - name: Configure Poetry | |
| run: | | |
| cd docs | |
| poetry config virtualenvs.in-project true | |
| - name: Cache Poetry dependencies | |
| uses: actions/cache@v4 | |
| with: | |
| path: docs/.venv | |
| key: ${{ runner.os }}-poetry-${{ hashFiles('docs/pyproject.toml') }} | |
| restore-keys: | | |
| ${{ runner.os }}-poetry- | |
| - name: Install documentation dependencies | |
| run: | | |
| cd docs | |
| poetry install --no-interaction --no-ansi | |
| - name: Cache cargo build | |
| uses: actions/cache@v4 | |
| with: | |
| path: | | |
| ~/.cargo/registry | |
| ~/.cargo/git | |
| target | |
| key: ${{ runner.os }}-cargo-docs-${{ hashFiles('**/Cargo.lock') }} | |
| restore-keys: | | |
| ${{ runner.os }}-cargo-docs- | |
| - name: Build documentation | |
| # CALM diagrams were rendered by the calm-diagrams job and downloaded | |
| # above, so skip the local re-render via the Makefile. | |
| env: | |
| SKIP_CALM_DIAGRAMS: "1" | |
| run: make docs | |
| - name: Check for broken links | |
| if: github.event_name == 'pull_request' | |
| continue-on-error: true | |
| run: | | |
| npm install -g linkinator | |
| linkinator docs/site/ --recurse --skip "rustdoc/.*" --verbosity error | |
| - name: Setup Pages | |
| if: github.ref == 'refs/heads/main' | |
| uses: actions/configure-pages@v5 | |
| - name: Upload Pages artifact | |
| if: github.ref == 'refs/heads/main' | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: docs/site | |
| deploy: | |
| name: 🚀 Deploy to GitHub Pages | |
| if: github.ref == 'refs/heads/main' | |
| needs: build | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |