documentation-tests.yaml

name: Documentation build and test
on:
  workflow_dispatch:
    inputs:
      documentation_branch:
        description: 'Documentation branch name'
        required: true
        type: string
        default: 'master'

  push:
    branches:
      - 'master'
    paths-ignore:
      - '**.md'
      - '**.txt'
      - '!**/CMakeLists.txt'

  pull_request:
    branches:
      - 'master'
    paths-ignore:
      - '**.md'
      - '**.txt'
      - '!**/CMakeLists.txt'

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

env:
  ACTION_BRANCH_NAME: ${{ github.ref }}

jobs:
  ubuntu-build-and-test-documentation:
    name: Documentation build and test

    if: ${{ !(contains(github.event.pull_request.labels.*.name, 'no-test') ||
              contains(github.event.pull_request.labels.*.name, 'skip-ci')) }}

    runs-on: ubuntu-22.04
    steps:
      - name: Sync eProsima/Fast-DDS repository
        uses: actions/checkout@v3
        with:
          path: src/fastrtps
          submodules: true

      - name: Install Fast DDS packages
        uses: ./src/fastrtps/.github/actions/install-apt-packages

      - name: Install documentation packages
        uses: ./src/fastrtps/.github/actions/install-apt-packages-documentation

      - name: Setup CCache
        uses: eProsima/eProsima-CI/external/setup-ccache-action@v0

      - name: Download FastDDS dependencies
        run: |
          pip3 install vcstool
          vcs import --skip-existing src < ./src/fastrtps/fastrtps.repos

      - name: Determine the Fast DDS Documentation branch to be used
        run: |
          if [[ ${{ github.event_name }} == "push" ]]
          then
            echo "ACTION_BRANCH_NAME=${{ github.ref }}" >> $GITHUB_ENV
            echo "Push event: using pushed branch '${{ github.ref }}' for docs repository"

          elif [[ ${{ github.event_name }} == "workflow_dispatch" ]]
          then
            echo "ACTION_BRANCH_NAME=${{ inputs.documentation_branch }}" >> $GITHUB_ENV
            echo "Workflow dispatch event: using input branch '${{ inputs.documentation_branch }}' for docs repository"

          elif [[ ${{ github.event_name }} == "pull_request" ]]
          then
            DOCS_REPO=https://github.com/eProsima/fast-dds-docs.git

            # Attempt to use PR's source branch
            TEMP_BRANCH=${{ github.head_ref }}
            RESPONSE_CODE=$(git ls-remote --heads $DOCS_REPO $TEMP_BRANCH | wc -l)

            if [[ ${RESPONSE_CODE} == "0" ]]
            then
              echo "PR source branch '$TEMP_BRANCH' branch DOES NOT exist in $DOCS_REPO"

              # Attempt to use PR's base branch
              TEMP_BRANCH=${{ github.base_ref }}
              RESPONSE_CODE=$(git ls-remote --heads $DOCS_REPO $TEMP_BRANCH | wc -l)

              if [[ ${RESPONSE_CODE} == "0" ]]
              then
                echo "PR base branch '$TEMP_BRANCH' branch DOES NOT exist in $DOCS_REPO"

                # Attempt to use version's branch, which will most likely be the base anyways.
                # This is just in case the PR was to an intermediate branch
                TEMP_BRANCH=master
                RESPONSE_CODE=$(git ls-remote --heads $DOCS_REPO $TEMP_BRANCH | wc -l)

                if [[ ${RESPONSE_CODE} == "0" ]]
                then
                  # There are no more fallbacks, so we need to fail here
                  echo "Version branch '$TEMP_BRANCH' branch DOES NOT exist in $DOCS_REPO"
                  exit 1
                fi
              fi
            fi

            echo "ACTION_BRANCH_NAME=$TEMP_BRANCH" >> $GITHUB_ENV
            echo "PR event: using deduced branch '$TEMP_BRANCH' for docs repository"
          fi

      - name: Download FastDDS documentation repo
        uses: actions/checkout@v4
        with:
          repository: eProsima/Fast-DDS-docs
          path: src/fastdds-docs
          ref: ${{ env.ACTION_BRANCH_NAME }}

      - name: Install colcon
        uses: eProsima/eProsima-CI/ubuntu/install_colcon@v0

      - name: Install required python packages
        uses: eProsima/eProsima-CI/ubuntu/install_python_packages@v0
        with:
          upgrade: false
          requirements_file_name: src/fastdds-docs/docs/requirements.txt

      - name: Build documentation
        run: |
          colcon build --event-handlers=console_direct+ --metas

      - name: Run documentation tests
        run: |
          colcon test --event-handlers=console_direct+ --packages-select fastdds-docs --return-code-on-test-failure