docs: turn the README into a project guide #10
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: documentation | |
| on: | |
| push: | |
| branches: [main] | |
| pull_request: | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| concurrency: | |
| group: documentation-${{ github.event.pull_request.number || github.ref }} | |
| cancel-in-progress: true | |
| jobs: | |
| build: | |
| name: compile documentation | |
| runs-on: ubuntu-24.04 | |
| steps: | |
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| with: | |
| persist-credentials: false | |
| - name: Install the pinned Rust toolchain | |
| run: | | |
| rustup toolchain install 1.98.0 --profile minimal | |
| rustup default 1.98.0 | |
| - name: Install the pinned documentation renderer | |
| run: cargo xtask docs-setup | |
| - name: Install the pinned browser renderer | |
| run: cargo xtask browser-install | |
| - name: Compile and validate the site and technical manuscript | |
| env: | |
| # The disposable hosted runner cannot use Chrome's Linux namespace sandbox. | |
| NUIF_CHROME_NO_SANDBOX: "1" | |
| run: cargo xtask docs-paper | |
| - name: Retain the compiled site and validation report | |
| uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 | |
| with: | |
| name: documentation-site | |
| if-no-files-found: error | |
| retention-days: 14 | |
| path: | | |
| target/docs-site | |
| target/research-manuscript.pdf | |
| target/documentation-catalog.json | |
| target/documentation-report.json | |
| - name: Assemble the Pages artifact | |
| if: github.event_name != 'pull_request' | |
| uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0 | |
| with: | |
| path: target/docs-site | |
| deploy: | |
| name: deploy documentation | |
| if: github.event_name != 'pull_request' | |
| needs: build | |
| runs-on: ubuntu-24.04 | |
| permissions: | |
| pages: write # publish the compiled documentation artifact | |
| id-token: write # mint the OIDC identity used by GitHub Pages | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - name: Deploy the Pages artifact | |
| id: deployment | |
| uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0 |