Make the docs build resilient: drop blockdiag, pin deps, modernize CI #576
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
| --- | |
| # Tools that can save round-trips to github and a lot of time: | |
| # | |
| # yamllint -f parsable pull_request.yml | |
| # pip3 install ruamel.yaml.cmd | |
| # yaml merge-expand pull_request.yml exp.yml && | |
| # diff -w -u pull_request.yml exp.yml | |
| # | |
| # github.com also has a powerful web editor that can be used without | |
| # committing. | |
| name: Build and Deploy | |
| # yamllint disable-line rule:truthy | |
| on: | |
| push: | |
| branches: | |
| - master | |
| - publish | |
| pull_request: | |
| branches: [master] | |
| # Allows you to run this workflow manually from the Actions tab | |
| workflow_dispatch: | |
| # As of January 2021, no YAML anchors :-( | |
| env: | |
| ubuntu_base_deps: doxygen make default-jre graphviz cmake ninja-build | |
| # The single Python version used to produce the published HTML, picked | |
| # out of the matrix below to avoid duplicate deploy artifacts. | |
| publish_python: '3.13' | |
| jobs: | |
| supported-reqs: | |
| name: 'Supported build (Python ${{ matrix.python-version }})' | |
| runs-on: ubuntu-latest | |
| # Build against the lockfile on more than one Python so that a pinned | |
| # dependency dropping support for a given interpreter is caught here | |
| # rather than by a contributor months later. | |
| strategy: | |
| fail-fast: false | |
| matrix: | |
| python-version: ['3.11', '3.13'] | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: ${{ matrix.python-version }} | |
| - name: apt-get install base dependencies | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get -y install $ubuntu_base_deps | |
| # Reproducible install: requirements.txt is the top-level list, | |
| # constraints.txt pins the full transitive tree to validated versions. | |
| - name: 'pip install -r requirements.txt -c constraints.txt' | |
| run: pip install -r scripts/requirements.txt -c scripts/constraints.txt | |
| - name: configure and build SOF API docs (Doxygen) | |
| run: | | |
| git clone https://github.com/thesofproject/sof | |
| cmake -GNinja -S sof/doc -B _build_doxy | |
| # Build the API XML up front. The html build below is strict | |
| # (-W), so any doc/source drift -- e.g. a doxygengroup that no | |
| # longer exists in sof -- fails the PR here instead of silently | |
| # dropping API sections. | |
| ninja -C _build_doxy doc | |
| # SOF_DOC_BUILD overrides the Makefile default (../sof/build_doxygen, | |
| # the documented sibling layout) because CI checks sof out *inside* | |
| # the sof-docs workspace rather than alongside it. | |
| - name: build | |
| run: | | |
| make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy | |
| du -shc _build*/* | |
| # Publish only from the canonical Python version so the matrix does | |
| # not upload the "html" artifact twice. | |
| - name: prepare file for deploy | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} | |
| run: ./.github/actions/create-publish-folder.sh | |
| # store the build result to artifact, used for later deploy or | |
| # download for debug | |
| # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts | |
| - name: upload HTML for deploy | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' && matrix.python-version == env.publish_python }} | |
| uses: actions/upload-artifact@v4 | |
| with: | |
| name: html | |
| path: _build/html | |
| deploy: | |
| needs: supported-reqs | |
| runs-on: ubuntu-latest | |
| if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/publish' }} | |
| steps: | |
| # download the build result from the same workflow | |
| # https://docs.github.com/en/actions/guides/storing-workflow-data-as-artifacts | |
| - name: download HTML | |
| uses: actions/download-artifact@v4 | |
| with: | |
| name: html | |
| path: html | |
| - name: deploy | |
| uses: peaceiris/actions-gh-pages@v3 | |
| with: | |
| personal_token: ${{ secrets.ACTIONS_DEPLOY_KEY }} | |
| publish_dir: ./html/ | |
| publish_branch: master | |
| external_repository: thesofproject/thesofproject.github.io | |
| lax: | |
| name: "Lax requirements (unpinned)" | |
| runs-on: ubuntu-latest | |
| # Makefile downgrades the Sphinx warnings, they are not errors any more | |
| env: {LAX: 1} | |
| steps: | |
| - uses: actions/checkout@v4 | |
| - uses: actions/setup-python@v5 | |
| with: | |
| python-version: '3.13' | |
| - name: apt-get install base dependencies | |
| run: | | |
| sudo apt-get update | |
| sudo apt-get -y install $ubuntu_base_deps | |
| # Unpinned "best effort" install of the loose requirements, the path | |
| # a drive-by contributor would take. No lockfile on purpose. | |
| - name: 'pip install -r scripts/requirements-lax.txt' | |
| run: pip install -r scripts/requirements-lax.txt | |
| - name: config tweaks | |
| run: | | |
| # We don't want plantUML to raise the contribution bar | |
| sed -i -e 's/^\(plantuml_output_format *=\).*/\1 "none"/' conf.py | |
| - name: configure and build SOF API docs (Doxygen) | |
| run: | | |
| git clone https://github.com/thesofproject/sof | |
| cmake -GNinja -S sof/doc -B _build_doxy | |
| ninja -C _build_doxy doc | |
| - name: build | |
| run: | | |
| make html VERBOSE=1 SOF_DOC_BUILD=_build_doxy | |
| du -shc _build*/* |