ci_cd.yml

name: GitHub CI

on:
  pull_request:
  workflow_dispatch:
    inputs:
      revn:
        type: choice
        options:
        - '252'
        - '251'
        - '242'
        - '241'
        - '232'
        description: 'The Mechanical revision number to run tests on.'
        default: '251' #stable version is 251, must match $stable_container
  schedule:
    - cron: '00 22 * * *'  # UTC time, may start 5-15 mins later than scheduled time
  # registry_package:
    # Run workflow when package is published or updated
    # types: [published]
  push:
    tags:
      - "*"
    branches:
      - main
      - release/*



env:
  PYMECHANICAL_PORT: 10000  # default won't work on GitHub runners
  PYMECHANICAL_START_INSTANCE: false
  DOCKER_PACKAGE: ghcr.io/ansys/mechanical
  DOCKER_MECH_CONTAINER_NAME: mechanical
  PACKAGE_NAME: ansys-mechanical-core
  DOCUMENTATION_CNAME: mechanical.docs.pyansys.com
  MAIN_PYTHON_VERSION: '3.13'
  # DEV_REVN & its Docker image are used in scheduled or registry package runs
  STABLE_REVN: '251'
  DEV_REVN: '252'
  LICENSE_SERVER: ${{ secrets.LICENSE_SERVER }}
  ANSYSLMD_LICENSE_FILE: 1055@${{ secrets.LICENSE_SERVER }}

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  update-changelog:
    name: "Update CHANGELOG for new tag"
    if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: ansys/actions/doc-deploy-changelog@v8
        with:
          token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}

  style:
    name: Code style
    runs-on: ubuntu-latest
    steps:
      - name: PyAnsys code style checks
        uses: ansys/actions/code-style@v8
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

  doc-style:
    name: Documentation Style Check
    runs-on: ubuntu-latest
    steps:
      - name: PyAnsys documentation style checks
        uses: ansys/actions/doc-style@v8
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

  vulnerabilities:
    name: Vulnerabilities
    runs-on: ubuntu-latest
    steps:
      - name: PyAnsys Vulnerability check (on main)
        if: github.ref == 'refs/heads/main'
        uses: ansys/actions/check-vulnerabilities@v8
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}
          python-package-name: ${{ env.PACKAGE_NAME }}
          token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}

      - name: PyAnsys Vulnerability check (on dev mode)
        if: github.ref != 'refs/heads/main'
        uses: ansys/actions/check-vulnerabilities@v8
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}
          python-package-name: ${{ env.PACKAGE_NAME }}
          token: ${{ secrets.PYANSYS_CI_BOT_TOKEN }}
          dev-mode: true

  smoke-tests:
    name: Build and Smoke tests
    runs-on: ${{ matrix.os }}
    needs: [style]
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ['3.10', '3.11', '3.12', '3.13']
        should-release:
          - ${{ github.event_name == 'push' && contains(github.ref, 'refs/tags') }}
        exclude:
          - should-release: false
            os: macos-latest
    steps:
      - name: Build wheelhouse and perform smoke test
        uses: ansys/actions/build-wheelhouse@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}
          operating-system: ${{ matrix.os }}
          python-version: ${{ matrix.python-version }}

  revn-variations:
    name: Save variations of revn
    runs-on: ubuntu-latest
    outputs:
      stable_container: ${{ steps.save-versions.outputs.stable_container }}
      test_revn: '${{ steps.save-versions.outputs.test_revn }}'
      test_container: ${{ steps.save-versions.outputs.test_container }}
      test_docker_image_version: '${{ steps.save-versions.outputs.test_docker_image_version }}'
    steps:
      - id: save-versions
        run: |
          if ${{ github.event_name == 'schedule' }}; then
            echo "test_revn=${{ env.DEV_REVN}}" >> $GITHUB_OUTPUT
            test_mech_revn=${{ env.DEV_REVN}}
            test_mech_image_version=${test_mech_revn:0:2}.${test_mech_revn:2}_candidate
            echo "test_container=${{ env.DOCKER_PACKAGE }}:$test_mech_image_version" >> $GITHUB_OUTPUT
            echo "test_docker_image_version=$test_mech_image_version" >> $GITHUB_OUTPUT
          else
            if [[ -z "${{inputs.revn}}" ]]; then
              mech_revn=${{ env.STABLE_REVN }}
            else
              mech_revn=${{inputs.revn}}
            fi
            export mech_image_version=${mech_revn:0:2}.${mech_revn:2}.0
            echo "test_revn=$mech_revn" >> $GITHUB_OUTPUT
            echo "test_container=${{ env.DOCKER_PACKAGE }}:$mech_image_version" >> $GITHUB_OUTPUT
            echo "test_docker_image_version=$mech_image_version" >> $GITHUB_OUTPUT
          fi

          stable_mech_revn=${{ env.STABLE_REVN }}
          stable_mech_image_version=${mech_revn:0:2}.${mech_revn:2}.0
          echo "stable_container=${{ env.DOCKER_PACKAGE }}:$stable_mech_image_version" >> $GITHUB_OUTPUT

          echo $GITHUB_OUTPUT

          # --- Help ----
          # schedule nightly uses DEV_REVN candidate
          # PRs and merges use STABLE_REVN
          # Workflow dispatch can use any revision number

  config-matrix:
    runs-on: ubuntu-latest
    needs: [revn-variations]
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - id: set-matrix
        run: |
          # if a tag(release) is pushed, test all versions
          if ${{ github.event_name == 'push' }} && ${{ contains(github.ref, 'refs/tags') }}; then
            echo "matrix={\"mechanical-version\":['23.2.0', '24.1.0', '24.2.0', '25.1.0'],\"experimental\":[false]}" >> $GITHUB_OUTPUT
          else
            echo "matrix={\"mechanical-version\":['${{ needs.revn-variations.outputs.test_docker_image_version }}'],\"experimental\":[false]}" >> $GITHUB_OUTPUT
          fi
  container-stability-check:
    runs-on: ubuntu-latest
    needs: [revn-variations]
    outputs:
      container_stable_exit: ${{ steps.check_stability.outputs.container_stable_exit }}
    steps:
      - id: check_stability
        run: |
          sudo apt update
          sudo apt install bc -y
          container_version=$(echo "${{ needs.revn-variations.outputs.test_docker_image_version }}" | grep -o -E '[0-9]+(\.[0-9]+)?' | head -n 1)
          if (( $(echo "$container_version > 24.2" | bc -l) )); then
            echo "container_stable_exit=true" >> $GITHUB_OUTPUT
          else
            echo "container_stable_exit=false" >> $GITHUB_OUTPUT
          fi

  remote-connect:
    name: Remote connect testing and coverage - Mechanical ${{ matrix.mechanical-version }}
    runs-on: public-ubuntu-latest-8-cores
    needs: [style, revn-variations, config-matrix]
    continue-on-error: ${{ matrix.experimental }}
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.config-matrix.outputs.matrix) }}
    steps:
      - name: Login in Github Container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Pull, launch, and validate Mechanical service
        env:
          MECHANICAL_IMAGE: ${{ env.DOCKER_PACKAGE }}:${{ matrix.mechanical-version }}
        run: |
          docker pull ${{ env.MECHANICAL_IMAGE }}
          docker run --restart always --name ${{ env.DOCKER_MECH_CONTAINER_NAME }} -e ANSYSLMD_LICENSE_FILE=1055@${{ env.LICENSE_SERVER }} -p ${{ env.PYMECHANICAL_PORT }}:10000 ${{ env.MECHANICAL_IMAGE }} > log.txt &
          grep -q 'WB Initialize Done' <(timeout 60 tail -f log.txt)

      - name: Display info
        if: github.event_name == 'schedule'
        id: capture_info
        run: |
          IMAGE_NAME=${{ env.DOCKER_PACKAGE }}:${{ matrix.mechanical-version }}
          BUILD_DATE=$(docker run --rm --entrypoint head $IMAGE_NAME -n 1 /install/ansys_inc/v${{ needs.revn-variations.outputs.test_revn }}/aisol/CommonFiles/builddate.txt)
          PUSHED_AT=$(docker inspect --format='{{.Created}}' $IMAGE_NAME)
          echo "docker_info=$IMAGE_NAME was pushed at: $PUSHED_AT" >> $GITHUB_OUTPUT
          echo "::group::Docker Info"
          echo "docker_info=$PUSHED_AT" >> $GITHUB_OUTPUT
          echo "build_info=$BUILD_DATE" >> $GITHUB_OUTPUT
          echo "$IMAGE_NAME pushed at $PUSHED_AT"
          echo "Build date : $BUILD_DATE"
          echo "::endgroup::"

      - name: Testing
        uses: ansys/actions/tests-pytest@v8
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}
          pytest-markers: '-m remote_session_connect'
          pytest-extra-args: '-s --junitxml remote_results${{ env.MAIN_PYTHON_VERSION}}.xml'

      - name: Publish Test Report
        uses: mikepenz/action-junit-report@v5
        if: always()
        with:
          report_paths: '**/remote_results*.xml'
          check_name: Remote Connect Test Report ${{ env.MAIN_PYTHON_VERSION}}
          detailed_summary: true
          include_passed: true
          fail_on_failure: true

      - name: Upload coverage results
        uses: actions/upload-artifact@v4
        if: matrix.mechanical-version == needs.revn-variations.outputs.test_docker_image_version
        with:
          include-hidden-files: true
          name: coverage-tests
          path: .cov
          retention-days: 7

      - name: Upload coverage results (as .coverage)
        uses: actions/upload-artifact@v4
        if: matrix.mechanical-version == needs.revn-variations.outputs.test_docker_image_version
        with:
          include-hidden-files: true
          name: coverage-file-tests
          path: .coverage
          retention-days: 7

      - name: Get Mechanical container logs
        if: always()
        run: |
          docker logs ${{ env.DOCKER_MECH_CONTAINER_NAME }} > mechanical_tests_log-${{ matrix.mechanical-version }}.txt 2>&1
          echo CONTAINER LOGS OUTPUT
          cat mechanical_tests_log-${{ matrix.mechanical-version }}.txt
          echo CPU info
          lscpu

      - name: Upload container logs
        uses: actions/upload-artifact@v4
        with:
          name: mechanical_tests_log-${{ matrix.mechanical-version }}
          path: mechanical_tests_log-${{ matrix.mechanical-version }}.txt
          retention-days: 7

  embedding-rpc-tests:
    name: Embedding rpc testing and coverage
    runs-on: public-ubuntu-latest-8-cores
    timeout-minutes: 10
    needs: [smoke-tests, revn-variations, container-stability-check]
    container:
      image: ${{ needs.revn-variations.outputs.test_container }}
      options: --entrypoint /bin/bash
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.10', '3.11', '3.12', '3.13']

    steps:
      - uses: actions/checkout@v4
      - name: Set up python and pip
        run: |
          apt update
          apt install --reinstall ca-certificates
          apt install lsb-release xvfb software-properties-common -y
          add-apt-repository ppa:deadsnakes/ppa -y
          apt install -y python${{ matrix.python-version }} python${{ matrix.python-version }}-venv
          python${{ matrix.python-version }} -m venv /env

      - name: Install packages for testing
        run: |
          . /env/bin/activate
          pip install --upgrade pip
          pip install -e .[tests]
          pip install -e .[rpc]

      - name: Unit Testing and coverage
        env:
          ANSYS_WORKBENCH_LOGGING_CONSOLE: 0
          ANSYS_WORKBENCH_LOGGING: 0
          ANSYS_WORKBENCH_LOGGING_FILTER_LEVEL: 2
          PYTHONUNBUFFERED: 1
        run: |
          . /env/bin/activate
          # if [ "${{ needs.container-stability-check.outputs.container_stable_exit }}" = "true" ]; then
          #  xvfb-run mechanical-env pytest -m remote_session_connect --remote-server-type=rpyc -s --junitxml test_results${{ matrix.python-version }}.xml
          # else
          #   xvfb-run mechanical-env pytest -m remote_session_connect --remote-server-type=rpyc -s --junitxml test_results${{ matrix.python-version }}.xml || true
          # fi
          # cicd will always pass. This is done temporarily to avoid failing the build since rpc is not yet stable
          xvfb-run mechanical-env pytest -m remote_session_connect --remote-server-type=rpyc -s --junitxml test_results${{ matrix.python-version }}.xml || true
        continue-on-error: true

      - name: Upload coverage results
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-tests-embedding-rpc
          path: .cov
          retention-days: 7

      - name: Upload coverage results (as .coverage)
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-file-tests-embedding-rpc
          path: .coverage
          retention-days: 7

      - name: Publish Test Report
        uses: mikepenz/action-junit-report@v5
        if: always()
        with:
          report_paths: '**/test_results*.xml'
          check_name: Test Report ${{ matrix.python-version }}
          detailed_summary: true
          include_passed: true
          fail_on_failure: true


  embedding-tests:
    name: Embedding testing and coverage
    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: [smoke-tests, revn-variations, container-stability-check]
    container:
      image: ${{ needs.revn-variations.outputs.test_container }}
      options: --entrypoint /bin/bash
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.10', '3.11', '3.12', '3.13']

    steps:
      - uses: actions/checkout@v4
      - name: Set up python and pip
        run: |
          apt update
          apt install --reinstall ca-certificates
          apt install lsb-release xvfb software-properties-common -y
          add-apt-repository ppa:deadsnakes/ppa -y
          apt install -y python${{ matrix.python-version }} python${{ matrix.python-version }}-venv
          python${{ matrix.python-version }} -m venv /env

      - name: Install packages for testing
        run: |
          . /env/bin/activate
          pip install --upgrade pip
          pip install -e .[tests]

      - name: Unit Testing and coverage
        env:
          ANSYS_WORKBENCH_LOGGING_CONSOLE: 0
          ANSYS_WORKBENCH_LOGGING: 0
          ANSYS_WORKBENCH_LOGGING_FILTER_LEVEL: 2
          NUM_CORES: 1
          PYTHONUNBUFFERED: 1
        run: |
          . /env/bin/activate
          if [ "${{ needs.container-stability-check.outputs.container_stable_exit }}" = "true" ]; then
            xvfb-run mechanical-env pytest -m embedding -s --junitxml test_results${{ matrix.python-version }}.xml
          else
            xvfb-run mechanical-env pytest -m embedding -s --junitxml test_results${{ matrix.python-version }}.xml || true
          fi

      - name: Upload coverage results
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-tests-embedding
          path: .cov
          retention-days: 7

      - name: Upload coverage results (as .coverage)
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-file-tests-embedding
          path: .coverage
          retention-days: 7

      - name: Publish Test Report
        uses: mikepenz/action-junit-report@v5
        if: always()
        with:
          report_paths: '**/test_results*.xml'
          check_name: Test Report ${{ matrix.python-version }}
          detailed_summary: true
          include_passed: true
          fail_on_failure: true

  embedding-scripts-tests:
    name: Embedding scripts testing and coverage
    runs-on: ubuntu-latest
    timeout-minutes: 10
    needs: [smoke-tests, revn-variations]
    container:
      image: ${{ needs.revn-variations.outputs.test_container }}
      options: --entrypoint /bin/bash
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.10', '3.11', '3.12', '3.13']

    steps:
      - uses: actions/checkout@v4
      - name: Set up python and pip
        run: |
          apt update
          apt install --reinstall ca-certificates
          apt install lsb-release xvfb software-properties-common -y
          add-apt-repository ppa:deadsnakes/ppa -y
          apt install -y python${{ matrix.python-version }} python${{ matrix.python-version }}-venv
          python${{ matrix.python-version }} -m venv /env

      - name: Install packages for testing
        run: |
          . /env/bin/activate
          pip install --upgrade pip
          pip install -e .[tests]

      - name: Embedding scripts unit testing and coverage
        env:
          ANSYS_WORKBENCH_LOGGING_CONSOLE: 0
          ANSYS_WORKBENCH_LOGGING: 0
          ANSYS_WORKBENCH_LOGGING_FILTER_LEVEL: 2
          NUM_CORES: 1
          PYTHONUNBUFFERED: 1
        run: |
          . /env/bin/activate
          mechanical-env pytest -m embedding_scripts -s --junitxml test_results_embedding_scripts${{ matrix.python-version }}.xml
          pytest -m cli -s --junitxml test_results_cli_scripts${{ matrix.python-version }}.xml

      - name: Upload coverage results
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-tests-embedding-scripts
          path: .cov
          retention-days: 7

      - name: Upload coverage results (as .coverage)
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-file-tests-embedding-scripts
          path: .coverage
          retention-days: 7

      - name: Publish Test Report
        uses: mikepenz/action-junit-report@v5
        if: always()
        with:
          report_paths: '**/test_results*.xml'
          check_name: Test Report ${{ matrix.python-version }}
          detailed_summary: true
          include_passed: true
          fail_on_failure: true

  launch-tests:
    name: Launch testing and coverage
    runs-on: public-ubuntu-latest-8-cores
    timeout-minutes: 15
    container:
      image: ${{ needs.revn-variations.outputs.test_container }}
      options: --entrypoint /bin/bash
    needs: [ style, revn-variations, container-stability-check]
    strategy:
      fail-fast: false
      matrix:
        python-version: ['3.10', '3.11', '3.12', '3.13']

    steps:
      - uses: actions/checkout@v4
      - name: Set up python and pip
        run: |
          apt update
          apt install --reinstall ca-certificates
          apt install software-properties-common -y
          add-apt-repository ppa:deadsnakes/ppa -y
          apt install -y python${{ env.MAIN_PYTHON_VERSION }} python${{ env.MAIN_PYTHON_VERSION }}-venv
          python${{ env.MAIN_PYTHON_VERSION }} -m venv /env

      - name: Install dependencies
        run: |
          apt install -y lsb-release

      - name: Install packages for testing
        run: |
          . /env/bin/activate
          pip install .[tests]

      - name: Set environment variable
        run: echo "ANSYSCL${{ needs.revn-variations.outputs.test_revn }}_DIR=/install/ansys_inc/v${{ needs.revn-variations.outputs.test_revn }}/licensingclient" >> $GITHUB_ENV

      - name: Unit Testing and coverage
        env:
          ANSYS_WORKBENCH_LOGGING_CONSOLE: 0
        run: |
          unset PYMECHANICAL_PORT
          unset PYMECHANICAL_START_INSTANCE
          . /env/bin/activate
          if [ "${{ needs.container-stability-check.outputs.container_stable_exit }}" = "true" ]; then
            pytest -m remote_session_launch -s --junitxml launch_test_results${{ matrix.python-version }}.xml
          else
            pytest -m remote_session_launch -s --junitxml launch_test_results${{ matrix.python-version }}.xml || true
          fi

      - name: Publish Launch Test Report
        uses: mikepenz/action-junit-report@v5
        if: always()
        with:
          report_paths: '**/launch_test_results*.xml'
          check_name: Launch Test Report ${{ matrix.python-version }}
          detailed_summary: true
          include_passed: true
          fail_on_failure: true

      - name: Upload coverage results
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-tests-remote-session-launch
          path: .cov
          retention-days: 7

      - name: Upload coverage results (as .coverage)
        uses: actions/upload-artifact@v4
        if: env.MAIN_PYTHON_VERSION == matrix.python-version
        with:
          include-hidden-files: true
          name: coverage-file-tests-remote-session-launch
          path: .coverage
          retention-days: 7

  doc-build:
    name: Documentation
    runs-on: ubuntu-latest
    container:
      image: ${{ needs.revn-variations.outputs.test_container }}
      options: --entrypoint /bin/bash
    needs: [style, doc-style, revn-variations, container-stability-check]

    steps:

      - name: Install Git and checkout project
        uses: actions/checkout@v4

      - name: Set up Python
        run: |
          apt update
          apt install --reinstall ca-certificates
          apt install software-properties-common -y
          add-apt-repository ppa:deadsnakes/ppa -y
          apt install -y python${{ env.MAIN_PYTHON_VERSION }} python${{ env.MAIN_PYTHON_VERSION }}-venv
          python${{ env.MAIN_PYTHON_VERSION }} -m venv /env

      - name: Install system dependencies
        run: |
          apt update
          apt install make lsb-release xvfb poppler-utils -y
          apt install zip pandoc libgl1-mesa-glx mesa-utils texlive-latex-extra latexmk nodejs npm graphviz -y

      - name: Install gh cli
        run: |
          (type -p wget >/dev/null || (apt update && apt-get install wget -y)) \
          && mkdir -p -m 755 /etc/apt/keyrings \
          && wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
          && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
          && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
          && apt update \
          && apt install gh -y

      - name: Install quarto to build cheatsheet
        run: |
          echo ${{ secrets.GITHUB_TOKEN }} | gh auth login --with-token
          gh release download --repo github.com/quarto-dev/quarto-cli --pattern *linux-amd64.deb
          apt install ./quarto*linux-amd64.deb -y
          quarto install tool tinytex --log-level warning

      - name: Test quarto installation
        run: quarto --version

      - name: Install Python requirements
        run: |
          . /env/bin/activate
          pip install -e .[doc]

      - name: Build docs
        env:
          NUM_CORES: 1
          ANSYS_WORKBENCH_LOGGING_FILTER_LEVEL: 0
        run: |
          . /env/bin/activate
          # Make html or pdf doc
          make_doc() {
            # $1 is the type of file we are creating (html or pdf)

            # Need to unset PYMECHANICAL_PORT and PYMECHANICAL_START_INSTANCE when running code containing remote sessions
            unset PYMECHANICAL_PORT
            unset PYMECHANICAL_START_INSTANCE

            output_file=doc_$1_output.txt
            if [ "${{ needs.container-stability-check.outputs.container_stable_exit }}" = "true" ]; then
              xvfb-run mechanical-env make -C doc $1
            else
              xvfb-run mechanical-env make -C doc $1 > $output_file 2>&1 || true
              cat $output_file
              echo done running make
              validate_output $output_file
            fi
          }

          # Validate that the html or pdf build succeeded
          validate_output() {
            echo "validating output of build"
            # $1 is the file we are checking
            # cat $1
            #
            # Check if "build succeeded" string is present in doc_build_output.txt
            #
            if grep -q "build succeeded" $1; then
              echo "Documentation building succeeded"
            else
              echo "Documentation building failed"
              exit 1
            fi
          }

          # Make the html doc & validate results
          make_doc html

          # Make the pdf doc & validate results
          make_doc pdf

          # Make the pdf doc & validate results
          make_doc linkcheck

      - name: Upload HTML Documentation
        uses: actions/upload-artifact@v4
        with:
          name: documentation-html
          path: doc/_build/html
          retention-days: 7

      - name: Upload PDF Documentation
        uses: actions/upload-artifact@v4
        with:
          name: documentation-pdf
          path: doc/_build/latex/*.pdf
          retention-days: 7

  coverage:
    name: Merging coverage
    needs: [remote-connect, embedding-tests, embedding-scripts-tests, launch-tests]
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

      - name: Install coverage
        run: |
          rm -rf env
          python -m pip install -U pip
          pip install coverage
          pip install -e .

      - name: Create common coverage directory
        run: mkdir cov-dir

      - uses: actions/download-artifact@v4
        with:
          name: coverage-file-tests-embedding
          path: cov-dir/embedding

      - uses: actions/download-artifact@v4
        with:
          name: coverage-file-tests-embedding-rpc
          path: cov-dir/embedding-rpc

      - uses: actions/download-artifact@v4
        with:
          name: coverage-file-tests-embedding-scripts
          path: cov-dir/embedding-scripts

      - uses: actions/download-artifact@v4
        with:
          name: coverage-file-tests-remote-session-launch
          path: cov-dir/launch

      - uses: actions/download-artifact@v4
        with:
          name: coverage-file-tests
          path: cov-dir/normal

      - name: Display structure of downloaded files
        run: ls -Ra

      - name: Move files to common location
        run: |
          mv cov-dir/embedding/.coverage .coverage.Embedding
          mv cov-dir/embedding-rpc/.coverage .coverage.EmbeddingRPC
          mv cov-dir/embedding-scripts/.coverage .coverage.EmbeddingScripts
          mv cov-dir/launch/.coverage .coverage.Launch
          mv cov-dir/normal/.coverage .coverage.Normal
          rm -rf cov-dir

      - name: Generate .coveragerc file
        run: |
          cat > .coveragerc << 'EOF'

          # .coveragerc to control coverage.py
          [run]
          relative_files = True

          [paths]
          source =
              src/ansys/mechanical
              /opt/hostedtoolcache/**/ansys/mechanical
              /usr/local/lib/**/ansys/mechanical
              .venv/lib/**/ansys/mechanical
              /env/lib/**/ansys/mechanical

          EOF

      - name: Run coverage merge and show results
        run: |
          coverage combine --keep --debug=pathmap --rcfile=.coveragerc
          coverage report
          coverage html -d .coverage-combined/html
          coverage xml -o .coverage-combined/xml

      - name: Upload combined coverage results
        uses: actions/upload-artifact@v4
        with:
          include-hidden-files: true
          name: combined-coverage-results
          path: .coverage-combined
          retention-days: 7

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v5
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
        with:
          files: .coverage-combined/xml


  package:
    name: Package library
    needs: [smoke-tests, remote-connect, embedding-tests, embedding-scripts-tests, doc-build]
    runs-on: ubuntu-latest
    steps:
      - name: Build library source and wheel artifacts
        uses: ansys/actions/build-library@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}
          python-version: ${{ env.MAIN_PYTHON_VERSION }}

  release:
    name: Release project
    if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
    needs: [package, update-changelog]
    runs-on: ubuntu-latest
    steps:
      - name: Release to the public PyPI repository
        uses: ansys/actions/release-pypi-public@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}
          twine-username: "__token__"
          twine-token: ${{ secrets.PYPI_TOKEN }}

      - name: Release to GitHub
        uses: ansys/actions/release-github@v8
        with:
          library-name: ${{ env.PACKAGE_NAME }}

  upload_dev_docs:
    name: Upload dev documentation
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    needs: [package]
    steps:
      - name: Deploy the latest documentation
        uses: ansys/actions/doc-deploy-dev@v8
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}

  upload_docs_release:
    name: Upload release documentation
    if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
    runs-on: ubuntu-latest
    needs: [release]
    steps:
      - name: Deploy the stable documentation
        uses: ansys/actions/doc-deploy-stable@v8
        with:
          cname: ${{ env.DOCUMENTATION_CNAME }}
          token: ${{ secrets.GITHUB_TOKEN }}
          bot-user: ${{ secrets.PYANSYS_CI_BOT_USERNAME }}
          bot-email: ${{ secrets.PYANSYS_CI_BOT_EMAIL }}