felfert is publishing 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
| 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 }} |