docs: state the layer openblox occupies and the rule that bounds it #28
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 | |
| # Builds the documentation site and deploys it to GitHub Pages at openblox.sh. | |
| # | |
| # A pull request builds but does not deploy, so a broken docs build is a red check | |
| # rather than a broken site. Only main deploys. | |
| # | |
| # This workflow also publishes the badge endpoints the README reads. They are | |
| # measured from the Go source, which is why pkg/** is in the trigger: leave it | |
| # out and the badges freeze at whatever the last docs edit happened to see. | |
| on: | |
| push: | |
| branches: [main] | |
| paths: | |
| - 'docs/**' | |
| - 'pkg/**' | |
| - 'mkdocs.yml' | |
| - 'go.mod' | |
| - 'go.sum' | |
| - 'requirements-docs.txt' | |
| - '.github/scripts/badges.sh' | |
| - '.github/workflows/docs.yml' | |
| pull_request: | |
| paths: | |
| - 'docs/**' | |
| - 'pkg/**' | |
| - 'mkdocs.yml' | |
| - 'go.mod' | |
| - 'go.sum' | |
| - 'requirements-docs.txt' | |
| - '.github/scripts/badges.sh' | |
| - '.github/workflows/docs.yml' | |
| workflow_dispatch: | |
| permissions: | |
| contents: read | |
| concurrency: | |
| group: docs | |
| cancel-in-progress: false | |
| defaults: | |
| run: | |
| shell: bash | |
| jobs: | |
| build: | |
| name: Build | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 | |
| steps: | |
| - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 | |
| - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0 | |
| with: | |
| python-version: '3.12' | |
| cache: pip | |
| cache-dependency-path: requirements-docs.txt | |
| - name: Install | |
| run: pip install -r requirements-docs.txt | |
| # --strict turns warnings into errors, so a broken internal link or a page | |
| # missing from the nav fails here instead of shipping. | |
| - name: Build | |
| run: mkdocs build --strict | |
| - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 | |
| with: | |
| go-version-file: go.mod | |
| cache: true | |
| # Writes shields.io endpoint JSON into the site, so the README's numbers | |
| # are measured on every deploy rather than typed once and left to rot. | |
| - name: Badges | |
| run: .github/scripts/badges.sh site/badges | |
| - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0 | |
| with: | |
| path: site | |
| deploy: | |
| name: Deploy | |
| if: github.event_name != 'pull_request' | |
| needs: build | |
| runs-on: ubuntu-latest | |
| timeout-minutes: 10 | |
| permissions: | |
| pages: write | |
| id-token: write | |
| environment: | |
| name: github-pages | |
| url: ${{ steps.deployment.outputs.page_url }} | |
| steps: | |
| - id: deployment | |
| uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 |