[gh] Add GitHub Pages workflow for mdbook documentation

moidx · moidx · commit 1b0b17fc0b3d · 2025-09-29T12:08:01.000-07:00
- Add new github_pages.yml workflow for publishing mdbook docs
- Remove GitHub Pages deployment from docs.yml workflow
- Clean up docs.yml to focus on Rust API documentation only
- Use cargo xtask docs command to build mdbook documentation
- Deploy static files from target/book to GitHub Pages
- Separate concerns: docs.yml for API docs, github_pages.yml for site

Signed-off-by: Miguel Osorio &lt;miguelosorio@google.com&gt;
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -10,29 +10,22 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
   docs:
     name: Documentation
-    # Only run this job on the main branch
-    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     steps:
     - uses: actions/checkout@v5
-    
+
     - name: Install Rust toolchain
       uses: dtolnay/rust-toolchain@stable
       with:
         components: rust-docs
-    
+
     - name: Cache cargo registry
       uses: actions/cache@v4
       with:
@@ -41,40 +34,12 @@ jobs:
           ~/.cargo/git
           target
         key: ${{ runner.os }}-docs-cargo-${{ hashFiles('**/Cargo.lock') }}
-    
+
     - name: Build documentation
       run: cargo doc --all-features --no-deps --workspace
-    
-    - name: Create index.html redirect for GitHub Pages
-      run: |
-        cat > target/doc/index.html << 'EOF'
-        <!DOCTYPE html>
-        <html>
-        <head>
-            <meta http-equiv="refresh" content="0; url=openprot/">
-            <title>OpenProt Documentation</title>
-        </head>
-        <body>
-            <p>Redirecting to <a href="openprot/">OpenProt Documentation</a>...</p>
-        </body>
-        </html>
-        EOF
-    
+
     - name: Check for broken links in docs
       run: |
         cargo install cargo-deadlinks
         cargo deadlinks --check-http
       continue-on-error: true
-    
-    - name: Setup Pages
-      uses: actions/configure-pages@v5
-      
-    # Upload the 'github-pages' artifact
-    - name: Upload artifact
-      uses: actions/upload-pages-artifact@v4
-      with:
-        path: ./target/doc
-        
-    - name: Deploy to GitHub Pages
-      id: deployment
-      uses: actions/deploy-pages@v4
diff --git a/.github/workflows/github_pages.yml b/.github/workflows/github_pages.yml
@@ -0,0 +1,61 @@
+# Licensed under the Apache-2.0 license
+
+name: GitHub Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build-and-deploy:
+    name: Build and Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v5
+
+    - name: Install Rust toolchain
+      uses: dtolnay/rust-toolchain@stable
+      with:
+        components: rust-docs
+
+    - name: Cache cargo registry
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+          target
+        key: ${{ runner.os }}-github-pages-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+    - name: Install mdbook and mdbook-mermaid
+      run: |
+        cargo install mdbook --locked
+        cargo install mdbook-mermaid --locked
+
+    - name: Build mdbook documentation
+      run: cargo xtask docs
+
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: ./target/book
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
