docs.yml

# YAML schema for GitHub Actions:
# https://help.github.com/en/actions/automating-your-workflow-with-github-actions/workflow-syntax-for-github-actions
#
# Helpful YAML parser to clarify YAML syntax:
# https://yaml-online-parser.appspot.com/
#
# This workflow uses actions that are not certified by GitHub. They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support documentation.
#
# This file contains the workflows that are run prior to merging a pull request.

name: Build Documentation

on:
  # Allow manually triggering of the workflow.
  workflow_dispatch: {}

  # Allow workflow to be called from another.
  workflow_call:
    inputs:
      docs_artifact_name:
        description: 'The name to be given to the uploaded docs artifact.'
        default: ""
        required: true
        type: string

env:
  DOC_BUILDER_IMAGE: 'ghcr.io/xmos/doc_builder:v3.0.0'
  DOCS_ARTIFACT_NAME: "xcore_sdk_docs"

jobs:
  build_documentation:
    name: Build documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive
      
      - name: Pull doc_builder docker image
        run: |
          docker pull ${DOC_BUILDER_IMAGE}
      
      - name: Build
        run: |
          docker run --rm -t -u $(id -u):$(id -g) -v ${{ github.workspace }}:/build -e PDF=1 -e REPO:/build -e EXCLUDE_PATTERNS=/build/doc/exclude_patterns.inc -e DOXYGEN_INCLUDE=/build/doc/Doxyfile.inc -e DOXYGEN_INPUT=ignore ${DOC_BUILDER_IMAGE}
          rm -rf doc/_build/_doxygen

      - name: Determine artifact names
        run: |
          if [ ! -z "${{ inputs.docs_artifact_name }}" ]; then
            echo "DOCS_ARTIFACT_NAME=${{ inputs.docs_artifact_name }}" >> $GITHUB_ENV
          fi

      - name: Save doc artifacts
        uses: actions/upload-artifact@v3
        with:
          name: ${{ env.DOCS_ARTIFACT_NAME }}
          path: doc/_build
          if-no-files-found: error # 'warn' or 'ignore' are also available, defaults to `warn`