FauxDB Documentation #4
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: FauxDB Documentation | |
| # Only run manually for documentation builds | |
| on: | |
| workflow_dispatch: | |
| inputs: | |
| build_type: | |
| description: 'Type of documentation build' | |
| required: true | |
| default: 'full' | |
| type: choice | |
| options: | |
| - full | |
| - quick | |
| - api-only | |
| deploy: | |
| description: 'Deploy to GitHub Pages' | |
| required: false | |
| default: true | |
| type: boolean | |
| environment: | |
| description: 'Deployment environment' | |
| required: true | |
| default: 'production' | |
| type: choice | |
| options: | |
| - production | |
| - preview | |
| version: | |
| description: 'Documentation version (leave empty for latest)' | |
| required: false | |
| type: string | |
| # Allow GitHub Pages deployment | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Ensure only one deployment runs at a time | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| env: | |
| CARGO_TERM_COLOR: always | |
| jobs: | |
| setup: | |
| name: Setup Documentation Environment | |
| runs-on: ubuntu-latest | |
| outputs: | |
| docs-version: ${{ steps.version.outputs.version }} | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| - name: Set documentation version | |
| id: version | |
| run: | | |
| if [ -n "${{ github.event.inputs.version }}" ]; then | |
| echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT | |
| else | |
| # Get version from Cargo.toml or git tag | |
| if [ -f "Cargo.toml" ]; then | |
| VERSION=$(grep '^version = ' Cargo.toml | cut -d'"' -f2) | |
| echo "version=$VERSION" >> $GITHUB_OUTPUT | |
| else | |
| echo "version=latest" >> $GITHUB_OUTPUT | |
| fi | |
| fi | |
| echo "📚 Documentation version: ${{ steps.version.outputs.version }}" | |
| build-docs: | |
| name: Build Documentation | |
| runs-on: ubuntu-latest | |
| needs: setup | |
| if: ${{ github.event.inputs.build_type == 'full' || github.event.inputs.build_type == 'quick' }} | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| with: | |
| fetch-depth: 0 | |
| # FIXED: Removed Node.js setup - using pure Rust/mdbook solution | |
| - name: Setup Rust toolchain | |
| uses: dtolnay/rust-toolchain@stable | |
| with: | |
| components: rustfmt, clippy, rust-docs | |
| - name: Install system dependencies | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y \ | |
| libssl-dev \ | |
| pkg-config \ | |
| build-essential \ | |
| ca-certificates \ | |
| curl \ | |
| gnupg \ | |
| lsb-release | |
| # Install PostgreSQL development packages without conflicts | |
| sudo apt-get install -y postgresql-client-common libpq-dev | |
| - name: Cache Rust dependencies | |
| uses: actions/cache@v4 | |
| with: | |
| path: | | |
| ~/.cargo/registry | |
| ~/.cargo/git | |
| target | |
| key: ${{ runner.os }}-cargo-docs-${{ hashFiles('**/Cargo.lock') }} | |
| restore-keys: | | |
| ${{ runner.os }}-cargo-docs- | |
| - name: Install documentation dependencies | |
| run: | | |
| # Install mdbook and related tools | |
| cargo install mdbook mdbook-mermaid mdbook-graphviz mdbook-toc | |
| - name: Build Rust documentation | |
| run: | | |
| # Build library documentation | |
| cargo doc --no-deps --document-private-items | |
| # Build API documentation with examples | |
| cargo doc --package fauxdb --no-deps --document-private-items --features full | |
| - name: Build Markdown documentation | |
| run: | | |
| # Build main documentation with mdbook | |
| if [ -f "docs/book.toml" ]; then | |
| cd docs | |
| mdbook build | |
| # Copy API docs to book output | |
| cp -r ../target/doc book/html/api | |
| fi | |
| - name: Generate API reference | |
| run: | | |
| # Generate comprehensive API reference | |
| mkdir -p docs/_site/api | |
| # Copy rustdoc output | |
| cp -r target/doc/* docs/_site/api/ 2>/dev/null || true | |
| # Generate additional API documentation | |
| echo "# FauxDB API Reference" > docs/_site/api/README.md | |
| echo "" >> docs/_site/api/README.md | |
| echo "This directory contains the complete API reference for FauxDB." >> docs/_site/api/README.md | |
| echo "" >> docs/_site/api/README.md | |
| echo "## Quick Links" >> docs/_site/api/README.md | |
| echo "- [Main Library](fauxdb/index.html)" >> docs/_site/api/README.md | |
| echo "- [Error Types](fauxdb/error/index.html)" >> docs/_site/api/README.md | |
| echo "- [Configuration](fauxdb/config/index.html)" >> docs/_site/api/README.md | |
| echo "- [Server](fauxdb/production_server/index.html)" >> docs/_site/api/README.md | |
| - name: Generate search index | |
| run: | | |
| # Search index is automatically generated by mdbook | |
| echo "Search index will be generated by mdbook automatically" | |
| - name: Upload documentation artifacts | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: documentation-build | |
| path: | | |
| docs/_site | |
| target/doc | |
| retention-days: 30 | |
| build-api-docs: | |
| name: Build API Documentation Only | |
| runs-on: ubuntu-latest | |
| needs: setup | |
| if: ${{ github.event.inputs.build_type == 'api-only' }} | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v4 | |
| - name: Setup Rust toolchain | |
| uses: dtolnay/rust-toolchain@stable | |
| with: | |
| components: rust-docs | |
| - name: Cache Rust dependencies | |
| uses: actions/cache@v4 | |
| with: | |
| path: | | |
| ~/.cargo/registry | |
| ~/.cargo/git | |
| target | |
| key: ${{ runner.os }}-cargo-api-docs-${{ hashFiles('**/Cargo.lock') }} | |
| restore-keys: | | |
| ${{ runner.os }}-cargo-api-docs- | |
| - name: Build API documentation | |
| run: | | |
| # Build comprehensive API documentation | |
| cargo doc --no-deps --document-private-items --features full | |
| # Generate API overview | |
| mkdir -p api-docs | |
| echo "# FauxDB API Documentation" > api-docs/README.md | |
| echo "" >> api-docs/README.md | |
| echo "Version: ${{ needs.setup.outputs.docs-version }}" >> api-docs/README.md | |
| echo "Generated: $(date)" >> api-docs/README.md | |
| echo "" >> api-docs/README.md | |
| echo "## Quick Start" >> api-docs/README.md | |
| echo "" >> api-docs/README.md | |
| echo "\`\`\`rust" >> api-docs/README.md | |
| echo "use fauxdb::{ProductionFauxDBServer, ProductionConfig};" >> api-docs/README.md | |
| echo "" >> api-docs/README.md | |
| echo "let config = ProductionConfig::load_from_env()?;" >> api-docs/README.md | |
| echo "let server = ProductionFauxDBServer::new(config).await?;" >> api-docs/README.md | |
| echo "\`\`\`" >> api-docs/README.md | |
| - name: Upload API documentation artifacts | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: api-documentation | |
| path: | | |
| target/doc | |
| api-docs | |
| retention-days: 30 | |
| deploy-preview: | |
| name: Deploy Preview | |
| runs-on: ubuntu-latest | |
| needs: [setup, build-docs] | |
| if: ${{ github.event.inputs.deploy == 'true' && github.event.inputs.environment == 'preview' }} | |
| steps: | |
| - name: Download documentation artifacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: documentation-build | |
| path: ./docs-site | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v4 | |
| - name: Upload to Pages | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: ./docs-site | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 | |
| - name: Preview deployment notification | |
| run: | | |
| echo "🚀 Documentation preview deployed!" | |
| echo "" | |
| echo "📋 Deployment Details:" | |
| echo " Environment: Preview" | |
| echo " Version: ${{ needs.setup.outputs.docs-version }}" | |
| echo " Build Type: ${{ github.event.inputs.build_type }}" | |
| echo " Deployed by: ${{ github.actor }}" | |
| echo " Deployment URL: ${{ steps.deployment.outputs.page_url }}" | |
| echo "" | |
| echo "🔗 Access your preview at: ${{ steps.deployment.outputs.page_url }}" | |
| deploy-production: | |
| name: Deploy to Production | |
| runs-on: ubuntu-latest | |
| needs: [setup, build-docs] | |
| if: ${{ github.event.inputs.deploy == 'true' && github.event.inputs.environment == 'production' }} | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Download documentation artifacts | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: documentation-build | |
| path: ./docs-site | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v4 | |
| - name: Upload to Pages | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: ./docs-site | |
| - name: Deploy to GitHub Pages | |
| id: deployment | |
| uses: actions/deploy-pages@v4 | |
| - name: Production deployment notification | |
| run: | | |
| echo "🎉 Documentation deployed to production!" | |
| echo "" | |
| echo "📋 Deployment Details:" | |
| echo " Environment: Production" | |
| echo " Version: ${{ needs.setup.outputs.docs-version }}" | |
| echo " Build Type: ${{ github.event.inputs.build_type }}" | |
| echo " Deployed by: ${{ github.actor }}" | |
| echo " Production URL: https://pgelephant.github.io/fauxdb/" | |
| echo "" | |
| echo "✅ Documentation is now live at: https://pgelephant.github.io/fauxdb/" | |
| docs-summary: | |
| name: Documentation Build Summary | |
| runs-on: ubuntu-latest | |
| needs: [setup, build-docs, deploy-preview, deploy-production] | |
| if: always() | |
| steps: | |
| - name: Build summary | |
| run: | | |
| echo "📚 FauxDB Documentation Build Summary" | |
| echo "======================================" | |
| echo "" | |
| echo "📋 Build Details:" | |
| echo " Version: ${{ needs.setup.outputs.docs-version }}" | |
| echo " Build Type: ${{ github.event.inputs.build_type }}" | |
| echo " Environment: ${{ github.event.inputs.environment }}" | |
| echo " Deploy: ${{ github.event.inputs.deploy }}" | |
| echo " Triggered by: ${{ github.actor }}" | |
| echo "" | |
| echo "📊 Job Results:" | |
| echo " Setup: ${{ needs.setup.result }}" | |
| echo " Build Docs: ${{ needs.build-docs.result }}" | |
| echo " Deploy Preview: ${{ needs.deploy-preview.result }}" | |
| echo " Deploy Production: ${{ needs.deploy-production.result }}" | |
| echo "" | |
| if [ "${{ github.event.inputs.deploy }}" == "true" ]; then | |
| if [ "${{ github.event.inputs.environment }}" == "production" ]; then | |
| echo "🌐 Production URL: https://pgelephant.github.io/fauxdb/" | |
| else | |
| echo "🔍 Preview URL: Check deployment step output" | |
| fi | |
| else | |
| echo "📦 Documentation artifacts uploaded (no deployment)" | |
| fi | |
| echo "" | |
| echo "✅ Documentation build completed!" |