fugue/.github/workflows/docs.yml at 4329846f0606e0348fb825fc7a7036ec7ad8f18b · alexnodeland/fugue · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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