pull-request.yml

---
# 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.12', '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
          if ! grep -q "zephyr/include" sof/doc/sof.doxygen.in; then
            echo "INPUT += @top_srcdir@/zephyr/include" \
              >> sof/doc/sof.doxygen.in
          fi
          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
          if ! grep -q "zephyr/include" sof/doc/sof.doxygen.in; then
            echo "INPUT += @top_srcdir@/zephyr/include" \
              >> sof/doc/sof.doxygen.in
          fi
          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*/*