Docs #177
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: Docs | |
| on: | |
| push: | |
| branches: [main] | |
| paths: | |
| - "**.h" | |
| - "Doxyfile" | |
| - "docs/**" | |
| - ".github/workflows/docs.yml" | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| pages: write | |
| id-token: write | |
| # Serialize Pages deployments and let the in-progress one finish. GitHub's | |
| # Pages backend rejects a new deployment ("Deployment failed, try again | |
| # later") when a previous deployment is cancelled mid-flight, so a rapid | |
| # burst of pushes with cancel-in-progress: true poisons the next deploy. | |
| # With false, only one deployment runs at a time, queued runs superseded by | |
| # a newer one are skipped, and the running production deployment always | |
| # completes. This is GitHub's documented setting for Pages workflows. | |
| concurrency: | |
| group: "pages" | |
| cancel-in-progress: false | |
| jobs: | |
| build-docs: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - name: Install Doxygen | |
| run: sudo apt-get update && sudo apt-get install -y doxygen graphviz | |
| - name: Generate API reference | |
| run: doxygen Doxyfile | |
| - name: Upload Pages artifact | |
| uses: actions/upload-pages-artifact@v3 | |
| with: | |
| path: docs/api | |
| deploy: | |
| needs: build-docs | |
| runs-on: ubuntu-latest | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deploy1.outputs.page_url || steps.deploy2.outputs.page_url || steps.deploy3.outputs.page_url }} | |
| steps: | |
| # GitHub's Pages publish backend fails intermittently ("Deployment | |
| # failed, try again later") on an artifact that is otherwise fine: the | |
| # exact same upload succeeds on a later attempt. deploy-pages has no | |
| # cross-deployment retry (its error_count only tolerates status-poll | |
| # errors, not a terminal "failed" deployment), so each retry has to | |
| # create a fresh deployment, i.e. re-run the whole action. | |
| # | |
| # Up to three spaced attempts. The first two are continue-on-error so a | |
| # transient failure falls through to the next; the third is NOT, so if | |
| # Pages is genuinely down all three fail and the job goes red. Every | |
| # attempt is its own named step, visible in the log. | |
| - name: Deploy to GitHub Pages (attempt 1) | |
| id: deploy1 | |
| continue-on-error: true | |
| uses: actions/deploy-pages@v4 | |
| - name: Wait before attempt 2 | |
| if: steps.deploy1.outcome == 'failure' | |
| run: sleep 30 | |
| - name: Deploy to GitHub Pages (attempt 2) | |
| id: deploy2 | |
| if: steps.deploy1.outcome == 'failure' | |
| continue-on-error: true | |
| uses: actions/deploy-pages@v4 | |
| - name: Wait before attempt 3 | |
| if: steps.deploy1.outcome == 'failure' && steps.deploy2.outcome == 'failure' | |
| run: sleep 60 | |
| - name: Deploy to GitHub Pages (attempt 3, final) | |
| id: deploy3 | |
| if: steps.deploy1.outcome == 'failure' && steps.deploy2.outcome == 'failure' | |
| uses: actions/deploy-pages@v4 |