Update docs #3
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: Build WASM ──────────────────────────────────────────────────── | |
| build-wasm: | |
| name: Build WASM browser bundle | |
| runs-on: ubuntu-latest | |
| 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]" | |
| - name: Build browser WASM bundle from demo.ml | |
| run: | | |
| # WATCodeGenerator compiles demo.ml → WAT text → WASM binary. | |
| # Artifacts land in wasm-out/: | |
| # module.wat, module.wasm, host_shim.js, abi_manifest.json | |
| mkdir -p wasm-out | |
| multilingual build-wasm-bundle demo.ml --out-dir wasm-out | |
| # wabt provides wasm2wat for validating / inspecting the binary. | |
| # The primary .wat is already emitted by build-wasm-bundle above, | |
| # but wasm2wat gives a round-trip check and canonical text form. | |
| - name: Install wabt (wasm-validate, wasm2wat) | |
| run: sudo apt-get install -y wabt | |
| - name: Validate and normalise WAT | |
| run: | | |
| wasm-validate wasm-out/module.wasm | |
| # Overwrite with canonical round-trip WAT (catches any encoding drift). | |
| wasm2wat wasm-out/module.wasm -o wasm-out/module.wat | |
| - name: Rename artifacts to stable names | |
| run: | | |
| # Jekyll references these as assets/wasm/multilingual.* | |
| mv wasm-out/module.wasm wasm-out/multilingual.wasm | |
| mv wasm-out/module.wat wasm-out/multilingual.wat | |
| mv wasm-out/host_shim.js wasm-out/host_shim.js # keep name | |
| mv wasm-out/abi_manifest.json wasm-out/abi_manifest.json | |
| - name: Upload WASM artefacts | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: wasm-pkg | |
| path: wasm-out/ | |
| retention-days: 1 | |
| # ── Job 2: 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/ | |
| - 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 3: 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 |