docs: Fugue Explorables — interactive, data-first documentation rehau… #38
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
| name: Docs | |
| on: | |
| push: | |
| branches: [ main ] | |
| paths: | |
| - 'docs/**' | |
| - '.github/workflows/docs.yml' | |
| pull_request: | |
| branches: [ main ] | |
| paths: | |
| - 'docs/**' | |
| - '.github/workflows/docs.yml' | |
| jobs: | |
| # Job to test and validate documentation | |
| test: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout repository | |
| uses: actions/checkout@v4 | |
| - name: Install Rust toolchain | |
| uses: dtolnay/rust-toolchain@stable | |
| - name: Cache Cargo registry and target | |
| uses: actions/cache@v4 | |
| with: | |
| path: | | |
| ~/.cargo/bin/ | |
| ~/.cargo/registry/index/ | |
| ~/.cargo/registry/cache/ | |
| ~/.cargo/git/db/ | |
| target/ | |
| key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} | |
| restore-keys: | | |
| ${{ runner.os }}-cargo- | |
| - name: Install mdBook and plugins | |
| run: | | |
| # Check if tools are installed with correct major.minor version | |
| install_if_needed() { | |
| local tool=$1 | |
| local major_minor=$2 | |
| local cargo_version=$3 | |
| if command -v $tool &> /dev/null; then | |
| local current_version=$($tool --version | grep -oE 'v[0-9]+\.[0-9]+' | head -1) | |
| if [[ "$current_version" =~ v$major_minor ]]; then | |
| echo "$tool $current_version already installed and compatible, skipping" | |
| return | |
| else | |
| echo "$tool $current_version found but incompatible, updating to $cargo_version" | |
| fi | |
| else | |
| echo "Installing $tool $cargo_version" | |
| fi | |
| cargo install $tool --vers "$cargo_version" --locked --force | |
| } | |
| # Install mdBook with optimizations | |
| install_if_needed mdbook "0\.4" "^0.4" | |
| # Install plugins | |
| install_if_needed mdbook-admonish "1\." "^1.18" | |
| install_if_needed mdbook-mermaid "0\.14" "^0.14" | |
| install_if_needed mdbook-toc "0\.14" "^0.14" | |
| install_if_needed mdbook-katex "0\.9" "^0.9" | |
| # Note: linkcheck skipped due to issues with LaTeX math syntax | |
| - name: Cache mdBook build | |
| uses: actions/cache@v4 | |
| with: | |
| path: docs/book | |
| key: ${{ runner.os }}-mdbook-${{ hashFiles('docs/**/*.md', 'docs/book.toml') }} | |
| restore-keys: | | |
| ${{ runner.os }}-mdbook- | |
| - name: Build documentation (validates structure) | |
| run: | | |
| cd docs | |
| # Build without linkcheck to avoid false positives with LaTeX math | |
| # Linkcheck has issues with math equations like \[ and \] | |
| mdbook build --skip-preprocessor linkcheck || mdbook build | |
| - name: Validate documentation | |
| run: | | |
| cd docs | |
| # Note: Code examples use `rust,ignore` or `rust,no_run` flags | |
| # as many are fragments for illustration purposes. | |
| # Full examples are tested via `cargo test --examples` and `cargo test --doc` | |
| echo "Documentation structure validated successfully" | |
| - name: Test library documentation | |
| run: | | |
| # Test the library's rustdoc examples | |
| cargo test --doc | |
| - name: Upload built documentation | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: built-docs | |
| path: docs/book | |
| retention-days: 1 | |
| # Job to build and deploy (only on main branch) | |
| build-deploy: | |
| runs-on: ubuntu-latest | |
| needs: test | |
| if: github.ref == 'refs/heads/main' && github.event_name == 'push' | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Download built documentation | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: built-docs | |
| path: docs/book | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v5 | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: docs/book | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 |