action.yml

# Execute sphinx to generate and test documentation project.
#
# Runs on:
# - Ubuntu 20.04
# - Ubuntu 22.04
#
# NOTE: This action is only useful for documentation packages that uses cmake_utils.
#
# Steps:
# - Checkout repository and fetch unshallow to be able to compare.
# - Install packages required.
# - Download dev_utils last artifact to have access to cmake_utils.
# - Build documentation with colcon.
# - Run tests with colcon.
# - Upload documentation.
#
# Arguments:
# - docs_subpackage_name : name of the documentation package to build and test
# - specific_cmake_args : specific cmake args to build documentation package [-DBUILD_DOCS=ON -DBUILD_DOCS_TESTS=ON]
# - secret_token : secret github token to avoid WebRequest rate limit error. Call it with ${{ github.GITHUB_TOKEN }}.

name: sphinx_docs
description: Build and test documentation using sphinx

inputs:

  checkout_path:
    description: 'Path where the original repository will be downloaded (Default: <github-workspace>/src)'
    required: false
    default: 'src'

  docs_subpackage_name:
    description: Name of colcon subpackage that contains the sphinx documentation
    required: false
    default: ''

  specific_cmake_args:
    description: Arguments for colcon build
    required: false
    default: '-DBUILD_DOCS=ON -DBUILD_DOCS_TESTS=ON'

  # Pass argument {{ secrets.GITHUB_TOKEN }} from workflow
  secret_token:
    description: Secret token to authenticate the WebRequest so it does not get a rate limit error.
    required: false
    default: ''

  path_to_requirements:
    description: 'Path to requirements.txt file'
    required: false
    default: ''

  custom_version_build:
    description: >
      Version of Fast DDS build from eProsima-CI.
    required: false
    type: string
    default: 'v2'

  upload_artifact_name:
    description: >
      Name of the artifact to upload.
    required: false
    type: string
    default: 'Documentation'

  upload_artifact:
    description: >
      Whether to upload the generated documentation as an artifact or not.
    required: false
    type: boolean
    default: true

runs:
  using: composite
  steps:

    - name: Sync repository
      uses: eProsima/eProsima-CI/external/checkout@main
      with:
        path: ${{ inputs.checkout_path }}

    - name: Install docs dependencies
      uses: eProsima/eProsima-CI/ubuntu/install_documentation_requirements@main
      with:
        path_to_requirements: ${{ inputs.path_to_requirements }}

    - name: Install Colcon
      uses: eProsima/eProsima-CI/ubuntu/install_colcon@main

    - name: Download cmake_utils artifact
      uses: eProsima/eProsima-CI/multiplatform/download_dependency@main
      with:
        artifact_name: build_dev_utils_${{ inputs.custom_version_build }}_ubuntu-22.04_Release_nightly
        workflow_source: build_dev_utils.yml
        workflow_source_repository: eProsima/eProsima-CI
        target_workspace: '${{ github.workspace }}/install'
        secret_token: ${{ inputs.secret_token }}
        workflow_conclusion: completed

    - name: Build documentation with colcon
      uses: eProsima/eProsima-CI/ubuntu/colcon_build@main
      with:
        colcon_build_args: '--packages-select ${{ inputs.docs_subpackage_name }}'
        cmake_args: '${{ inputs.specific_cmake_args }}'
        workspace_dependencies: '${{ github.workspace }}/install'

    - name: Run colcon test of documentation
      uses: eProsima/eProsima-CI/ubuntu/colcon_test@main
      with:
        packages_names: ${{ inputs.docs_subpackage_name }}
        workspace_dependencies: '${{ github.workspace }}/install'

    - name: Upload documentation
      uses: eProsima/eProsima-CI/external/upload-artifact@main
      if: ${{ inputs.upload_artifact }}
      with:
        name: ${{ inputs.upload_artifact_name }}
        path: install/${{ inputs.docs_subpackage_name }}/docs/${{ inputs.docs_subpackage_name }}/sphinx/html/