publish-docs.yaml

name: Publish Sync docs to pages
run-name: ${{ github.actor }} is publishing docs
on:
  workflow_dispatch: # Allow manual triggering
  push:
    branches: [master, main]
    # paths: ['docs/**.md']  # API docs need building always

# This ensures any in-progress workflows in the same branch or PR
# are cancelled if there is a fresh push.
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
  cancel-in-progress: true # Skip any intermediate builds but finish deploying

jobs:
  build-mdbook:
    runs-on: ubuntu-latest
    env:
      MDBOOK_ENV: 0.5.2 # Current `mdbook` version. See `https://crates.io/crates/mdbook`.
      MERMAID_ENV: 0.17.0 # For crate `mdbook-mermaid`. See: `https://github.com/badboy/mdBook-mermaid/`. Always check version compatibility with mdbook.
      DEST_DIR: /home/runner/.cargo/bin
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false
      - uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
        with:
          path: |
            ~/.cargo/bin/
            ~/.cargo/registry/
            ~/.cargo/git/
            target/
          key: ${{ runner.os }}-cargo-mdbook-${{ hashFiles('**/Cargo.lock') }}
      - name: Install mdBook
        run: |
          export PATH=$PATH:$DEST_DIR
          curl -sSL "https://github.com/rust-lang/mdBook/releases/download/v$MDBOOK_ENV/mdbook-v$MDBOOK_ENV-x86_64-unknown-linux-gnu.tar.gz" | tar -xz --directory $DEST_DIR
          curl -sSL "https://github.com/badboy/mdBook-mermaid/releases/download/v$MERMAID_ENV/mdbook-mermaid-v$MERMAID_ENV-x86_64-unknown-linux-gnu.tar.gz" | tar -xz --directory $DEST_DIR
      - name: Build docs
        run: |
          cd docs
          echo Generating the cargo docs
          cargo doc --no-deps
          echo Generating mdbook - DEBUG mode for logging
          mdbook-mermaid install .
          MDBOOK_LOG=debug mdbook build -d output
          echo Generate the API docs
          mkdir -p output/api
          cargo doc --no-deps
          cp -r ../target/doc/* output/api
      - name: Upload mdBook artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: mdbook-output
          path: ./docs/output
          retention-days: 1

  build-openapi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          persist-credentials: false
      - uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5
        with:
          path: |
            ~/.cargo/bin/
            ~/.cargo/registry/
            ~/.cargo/git/
            target/
          key: ${{ runner.os }}-cargo-openapi-${{ hashFiles('**/Cargo.lock') }}
      - name: Generate OpenAPI spec and setup Swagger UI
        run: |
          echo "🔧 Generating OpenAPI specification..."
          cargo run --example generate_openapi_spec > openapi.json

          echo "Downloading Swagger UI..."
          SWAGGER_VERSION="5.10.0"
          wget -q "https://github.com/swagger-api/swagger-ui/archive/v${SWAGGER_VERSION}.tar.gz"
          tar -xzf "v${SWAGGER_VERSION}.tar.gz"

          echo "Setting up Swagger UI for deployment..."
          mkdir -p swagger-ui-dist
          cp -r "swagger-ui-${SWAGGER_VERSION}/dist/"* swagger-ui-dist/

          echo "Copying OpenAPI spec..."
          cp openapi.json swagger-ui-dist/openapi.json

          echo "Configuring Swagger UI to use our OpenAPI spec (replacing Petstore URL)..."
          sed -i 's|https://petstore.swagger.io/v2/swagger.json|./openapi.json|g' swagger-ui-dist/swagger-initializer.js

          echo "Updating page title..."
          sed -i 's|<title>Swagger UI</title>|<title>Syncstorage-rs API Documentation</title>|g' swagger-ui-dist/index.html

          echo "Swagger UI setup complete!"
      - name: Upload Swagger UI artifact
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: swagger-ui-output
          path: ./swagger-ui-dist
          retention-days: 1

  combine-and-prepare:
    needs: [build-mdbook, build-openapi]
    runs-on: ubuntu-latest
    steps:
      - name: Download mdBook artifact
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: mdbook-output
          path: ./output
      - name: Download Swagger UI artifact
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: swagger-ui-output
          path: ./output/swagger-ui
      - name: Debug output directory
        run: |
          echo "Checking combined output structure:"
          ls -lah output || true
          echo ""
          echo "Checking Rust API docs (output/api):"
          ls -lah output/api || true
          echo ""
          echo "Checking Swagger UI (output/swagger-ui):"
          ls -lah output/swagger-ui || true
          echo ""
          echo "Checking index.html files:"
          find output -maxdepth 3 -type f -name "index.html" -print || true
      - name: Upload combined artifact
        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: ./output

  deploy:
    needs: combine-and-prepare
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
      - name: Print deployed docs URL
        run: |
          echo "Documentation deployed successfully."
          echo "Main Documentation: ${PAGE_URL}"
          echo "Rust API Docs: ${PAGE_URL}api/"
          echo "OpenAPI/Swagger UI: ${PAGE_URL}swagger-ui/"

        env:
          PAGE_URL: ${{ steps.deployment.outputs.page_url }}