build-docs.yaml

#
#  Copyright 2023 Winford (Uncle Grumpy) <winford@object.stream>
#
#  SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later
#
# This is a workflow for atomvm/AtomVM to Publish API documentation and other content from the `doc` directory to
# atomvm.net hosted on GitHub Pages

name: Build Docs

# Controls when the workflow will run
on:
  # Triggers the workflow on push request and tag events on main branch
  pull_request:
    tags:
      - '**'
    branches:
      - 'main'
      - 'release-**'
    paths:
      - '.github/workflows/**'
      - 'CMakeLists.txt'
      - 'doc/**'
      - 'libs/**'
      - 'src/libAtomVM/**'
      - 'UPDATING.md'
      - 'CONTRIBUTING.md'
      - 'CHANGELOG.md'
      - 'CODE_OF_CONDUCT.md'
  push:
    repositories:
      - '!atomvm/AtomVM'
    paths:
      - '.github/workflows/**'
      - 'CMakeLists.txt'
      - 'doc/**'
      - 'libs/**'
      - 'src/libAtomVM/**'
      - 'UPDATING.md'
      - 'CONTRIBUTING.md'
      - 'CHANGELOG.md'
      - 'CODE_OF_CONDUCT.md'

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref != 'refs/heads/main' && github.ref || github.run_id }}
  cancel-in-progress: true

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:

    strategy:
      fail-fast: false
      ## don't add more than one OS to matrix, this is only to retrieve the full os-name for keeping cache in sync
      matrix:
        os: [ ubuntu-24.04 ]
    # The type of runner that the job will run on
    runs-on: ${{ matrix.os }}
    # Documentation currently fails to build with OTP-27 and recent OTP-26.
    container: erlang:26.0.2

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - name: Install Deps
        run: |
          apt update -y
          DEBIAN_FRONTEND=noninteractive apt install -y git cmake doxygen graphviz python3-pip python3-virtualenv python3-setuptools python3-stemmer wget

      - uses: actions/cache@v4
        id: sphinx-cache
        with:
          path: /home/runner/python-env/sphinx
          key: ${{ matrix.os }}-${{ job.container.id }}-sphinx-install

      - name: Install Sphinx
        if: ${{ steps.sphinx-cache.outputs.cache-hit != 'true' }}
        run: |
         virtualenv /home/runner/python-env/sphinx
          . /home/runner/python-env/sphinx/bin/activate
          python3 -m pip install sphinx
          python3 -m pip install myst-parser
          python3 -m pip install sphinx-rtd-theme
          python3 -m pip install rinohtype
          python3 -m pip install pillow
          python3 -m pip install gitpython
          python3 -m pip install breathe
          python3 -m pip install pygments

      - name: Set docs target name
        shell: bash
        run: |
            if [[ ${{ github.ref_name }} == *"/merge" ]]; then
              echo "AVM_DOCS_NAME=${{github.event.pull_request.base.ref}}" >> "$GITHUB_ENV";
            else
              echo "AVM_DOCS_NAME=${{ github.ref_name }}" >> "$GITHUB_ENV";
            fi

      - uses: actions/checkout@v4
        with:
          repository: ${{ vars.GITHUB_REPOSITORY }}
          fetch-depth: 0

      - name: Track all branches
        shell: bash
        run: |
          git config --global --add safe.directory /__w/AtomVM/AtomVM
          for branch in `git branch -a | grep "remotes/origin" | grep -v HEAD | grep -v  "${{ github.ref_name }}"`; do
            git branch --track ${branch#remotes/origin/} $branch
          done

      - name: Build Site
        id: build
        shell: bash
        run: |
          . /home/runner/python-env/sphinx/bin/activate
          git config --global --add safe.directory ${PWD}
          mkdir build
          cd build
          cmake ..
          cd doc
          make GitHub_CI_Publish_Docs