Update examples #15
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
| # Deploy multilingual docs to GitHub Pages. | |
| # | |
| # This workflow replaces GitHub's default Jekyll deployment so we can: | |
| # 1. Build the browser WASM bundle from demo.ml via WATCodeGenerator. | |
| # `multilingual build-wasm-bundle demo.ml` emits: | |
| # - module.wat (WebAssembly Text — educational display in docs) | |
| # - module.wasm (binary — executed in the browser REPL) | |
| # - host_shim.js (JS host import stubs for print_str, print_f64, …) | |
| # - abi_manifest.json (ABI metadata) | |
| # 2. Copy all bundle artifacts into assets/wasm/. | |
| # 3. Build the Jekyll site. | |
| # 4. Deploy _site/ to GitHub Pages. | |
| # | |
| # The build is purely Python-driven (multilingualprogramming[wasm]). | |
| # No Rust toolchain or wasm-pack is required. | |
| # | |
| # Trigger: every push to main, or manually via workflow_dispatch. | |
| name: Build and deploy docs | |
| on: | |
| push: | |
| branches: [main] | |
| workflow_dispatch: | |
| # Required for the deploy-pages action. | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Cancel in-progress runs on the same branch so pushes don't queue up. | |
| concurrency: | |
| group: pages-${{ github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| # ── Job 1: Test every executable doc block ──────────────────────────────── | |
| test-blocks: | |
| name: Test doc code blocks | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout docs repo | |
| uses: actions/checkout@v4 | |
| - name: Checkout multilingual source | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: johnsamuelwrites/multilingual | |
| path: multilingual-src | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.12' | |
| cache: pip | |
| cache-dependency-path: multilingual-src/pyproject.toml | |
| - name: Install multilingual with WASM extras | |
| working-directory: multilingual-src | |
| run: pip install -e ".[dev,wasm]" | |
| - name: Install wabt (wat2wasm, wasm-validate) | |
| run: sudo apt-get install -y wabt | |
| - name: Install pytest | |
| run: pip install pytest | |
| - name: Run code-block tests | |
| run: pytest _tests/ -v --tb=short | |
| # ── Job 2: Build WASM ──────────────────────────────────────────────────── | |
| build-wasm: | |
| name: Build WASM browser bundle | |
| runs-on: ubuntu-latest | |
| needs: test-blocks | |
| steps: | |
| - name: Checkout docs repo (for demo.ml) | |
| uses: actions/checkout@v4 | |
| - name: Checkout multilingual source | |
| uses: actions/checkout@v4 | |
| with: | |
| repository: johnsamuelwrites/multilingual | |
| path: multilingual-src | |
| - name: Set up Python | |
| uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.12' | |
| cache: pip | |
| cache-dependency-path: multilingual-src/pyproject.toml | |
| - name: Install multilingual with WASM extras | |
| working-directory: multilingual-src | |
| run: pip install -e ".[dev,wasm]" | |
| # wabt must be installed before the bundle build so wat2wasm is | |
| # available to assemble the WAT text → WASM binary. | |
| - name: Install wabt (wat2wasm, wasm-validate, wasm2wat) | |
| run: sudo apt-get install -y wabt | |
| - name: Build browser WASM bundle from demo.ml | |
| run: | | |
| # WATCodeGenerator compiles demo.ml → WAT text (module.wat). | |
| # Additional artifacts: host_shim.js, abi_manifest.json | |
| mkdir -p wasm-out | |
| multilingual build-wasm-bundle demo.ml --out-dir wasm-out | |
| - name: Assemble and validate demo WASM binary | |
| run: | | |
| # Assemble the canonical WAT text into a binary. | |
| # This works whether build-wasm-bundle emits .wasm or not; | |
| # we always produce the binary from the WAT source of truth. | |
| wat2wasm wasm-out/module.wat -o wasm-out/module.wasm | |
| wasm-validate wasm-out/module.wasm | |
| - name: Stage all WASM artifacts under assets/wasm/ | |
| run: | | |
| # Collect everything into assets/wasm/ so the artifact layout | |
| # matches the Jekyll source tree exactly. | |
| mkdir -p assets/wasm/blocks | |
| # Rename module.* → multilingual.* and move into assets/wasm/ | |
| mv wasm-out/module.wasm assets/wasm/multilingual.wasm | |
| mv wasm-out/module.wat assets/wasm/multilingual.wat | |
| mv wasm-out/host_shim.js assets/wasm/host_shim.js | |
| mv wasm-out/abi_manifest.json assets/wasm/abi_manifest.json | |
| # Per-block binaries compiled in the next step land in assets/wasm/blocks/ | |
| - name: Compile per-block WASM binaries | |
| run: | | |
| # Each executable code block in the docs gets its own WASM binary, | |
| # keyed by SHA-256 hash of its content, stored in assets/wasm/blocks/. | |
| # The browser Run button fetches the per-block binary and executes it, | |
| # falling back to the demo binary if a block wasn't compiled. | |
| python _scripts/compile_blocks.py | |
| - name: Upload WASM artefacts | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: wasm-pkg | |
| path: assets/wasm/ | |
| retention-days: 1 | |
| # ── Job 3: Build Jekyll ─────────────────────────────────────────────────── | |
| build-jekyll: | |
| name: Build Jekyll site | |
| runs-on: ubuntu-latest | |
| needs: build-wasm | |
| steps: | |
| - name: Checkout docs repo | |
| uses: actions/checkout@v4 | |
| - name: Download WASM artefacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: wasm-pkg | |
| path: assets/wasm/ | |
| # Downloaded layout (relative to repo root): | |
| # assets/wasm/multilingual.wasm, multilingual.wat, … | |
| # assets/wasm/blocks/<hash16>.wasm (one per compiled code block) | |
| - name: Set up Ruby | |
| uses: ruby/setup-ruby@v1 | |
| with: | |
| ruby-version: '3.3' | |
| bundler-cache: true # runs `bundle install` and caches gems | |
| - name: Configure GitHub Pages | |
| id: pages | |
| uses: actions/configure-pages@v5 | |
| # Jekyll is built with JEKYLL_ENV=production so jekyll-seo-tag, | |
| # jekyll-sitemap, etc. output canonical URLs correctly. | |
| - name: Build Jekyll site | |
| env: | |
| JEKYLL_ENV: production | |
| run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" | |
| - name: Upload Pages artefact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: _site/ | |
| # ── Job 4: Deploy ───────────────────────────────────────────────────────── | |
| deploy: | |
| name: Deploy to GitHub Pages | |
| runs-on: ubuntu-latest | |
| needs: build-jekyll | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deploy.outputs.page_url }} | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deploy | |
| uses: actions/deploy-pages@v4 |