Use GH pages to preview docs w/ PR and also deploy documentation #3
Workflow file for this run
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: Build and Deploy Docs | |
| on: | |
| push: | |
| branches: [ "master" ] | |
| pull_request: | |
| types: [opened, synchronize, reopened, ready_for_review] | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: true | |
| jobs: | |
| build: | |
| runs-on: ubuntu-latest | |
| if: ${{ github.event_name == 'push' || !github.event.pull_request.draft }} | |
| steps: | |
| - name: Checkout | |
| uses: actions/checkout@v4 | |
| - name: Setup Pages | |
| uses: actions/configure-pages@v5 | |
| - name: Install system deps | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get install -y doxygen graphviz | |
| python3 -m pip install --upgrade pip | |
| # Ensure mkdocs plugins in mkdocs.yml are available | |
| python3 -m pip install mkdocs mkdocs-material pymdown-extensions | |
| # Build API docs first so mkdocs can find docs/api/index.html referenced in nav | |
| - name: Build Doxygen | |
| run: | | |
| # Use repo Doxyfile; fallback to root if needed | |
| doxygen docs/Doxyfile || doxygen Doxyfile | |
| # Ensure doxygen HTML ends up in docs/api (expected by mkdocs.yml nav) | |
| if [ -d html ]; then mkdir -p docs/api && cp -a html/. docs/api/; fi | |
| if [ -d docs/html ]; then mkdir -p docs/api && cp -a docs/html/. docs/api/; fi | |
| - name: Build MkDocs | |
| run: | | |
| mkdocs build --strict --site-dir site | |
| - name: Upload artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: site | |
| deploy: | |
| if: > | |
| ${{ | |
| (github.event_name == 'push') || | |
| (github.event_name == 'pull_request' && | |
| github.event.pull_request.head.repo.full_name == github.repository) | |
| }} | |
| needs: build | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - id: deployment | |
| uses: actions/deploy-pages@v4 |