build_doc.yml

name: Documentation
on:
  pull_request:
    types:
      - opened
      - synchronize
      - reopened
      - ready_for_review
  merge_group:

concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref && github.ref || github.run_id }}
  cancel-in-progress: true

permissions: read-all

jobs:
  Smart_CI:
    runs-on: ubuntu-latest
    if: github.event.pull_request.draft == false || github.run_attempt > 1
    outputs:
      affected_components: "${{ steps.smart_ci.outputs.affected_components }}"
      changed_components: "${{ steps.smart_ci.outputs.changed_components }}"
    steps:
      - name: checkout action
        uses: ababushk/checkout@dd591a6a2ac25618db4eda86e7e0d938f88cf01b # cherry_pick_retries
        timeout-minutes: 15
        with:
          sparse-checkout: .github/actions/smart-ci

      - name: Get affected components
        id: smart_ci
        uses: ./.github/actions/smart-ci
        with:
          repository: ${{ github.repository }}
          pr: ${{ github.event.number }}
          commit_sha: ${{ github.sha }}
          ref_name: ${{ github.ref_name }}
          component_pattern: "category: (.*)"
          repo_token: ${{ secrets.GITHUB_TOKEN }}

      - name: Show affected components
        run: |
          echo "${{ toJSON(steps.smart_ci.outputs.affected_components) }}"
        shell: bash

  Docker:
    needs: Smart_CI
    runs-on: aks-linux-4-cores-16gb-docker-build
    container:
      image: openvinogithubactions.azurecr.io/docker_build:0.2
      volumes:
        - /mount:/mount
    outputs:
      images: "${{ steps.handle_docker.outputs.images && steps.handle_docker.outputs.images || steps.mock_image.outputs.images }}"
    steps:
      - name: Checkout
        uses: ababushk/checkout@dd591a6a2ac25618db4eda86e7e0d938f88cf01b # cherry_pick_retries
        timeout-minutes: 15

      - uses: ./.github/actions/handle_docker
        id: handle_docker
        with:
          images: |
            ov_build/ubuntu_22_04_x64
          registry: 'openvinogithubactions.azurecr.io'
          dockerfiles_root_dir: '.github/dockerfiles'
          changed_components: ${{ needs.smart_ci.outputs.changed_components }}

  Build_Doc:
    needs: [ Docker, Smart_CI ]
    if: ${{ github.repository_owner == 'openvinotoolkit' }}
    timeout-minutes: 20
    defaults:
      run:
        shell: bash
    runs-on: aks-linux-4-cores-16gb
    container:
      image: ${{ fromJSON(needs.docker.outputs.images).ov_build.ubuntu_22_04_x64 }}
      volumes:
        - /mount:/mount
        - /home/runner/secrets/:/secrets:ro
      options: -e SCCACHE_AZURE_BLOB_CONTAINER -v ${{ github.workspace }}:${{ github.workspace }}
    env:
      OPENVINO_REPO: ${{ github.workspace }}/openvino
      BUILD_DIR: ${{ github.workspace }}/build
      CMAKE_CXX_COMPILER_LAUNCHER: sccache
      CMAKE_C_COMPILER_LAUNCHER: sccache
      SCCACHE_IGNORE_SERVER_IO_ERROR: 1
      SCCACHE_SERVER_PORT: 35555
      SCCACHE_CACHE_SIZE: 50G
      SCCACHE_AZURE_KEY_PREFIX: build_docs
    steps:
      - name: Append the environment variable - load SCCACHE_AZURE_CONNECTION_STRING from file
        shell: bash
        run: |
          SCCACHE_AZURE_CONNECTION_STRING="$(cat /secrets/sccache/connection-string)"
          echo "::add-mask::${SCCACHE_AZURE_CONNECTION_STRING}"
          echo "SCCACHE_AZURE_CONNECTION_STRING=${SCCACHE_AZURE_CONNECTION_STRING}" >> $GITHUB_ENV
          echo "✓ Connection string loaded and masked"

      - name: Clone OpenVINO
        uses: ababushk/checkout@dd591a6a2ac25618db4eda86e7e0d938f88cf01b # cherry_pick_retries
        timeout-minutes: 15
        with:
          path: ${{ env.OPENVINO_REPO }}
          submodules: 'true'
          lfs: 'true'

      - name: Install python dependencies
        run: |
          python3 -m pip install -r ${OPENVINO_REPO}/docs/requirements.txt
          (cd ${OPENVINO_REPO}/docs/openvino_sphinx_theme && python3 -m pip install .)
          python3 -m pip install ${OPENVINO_REPO}/docs/openvino_custom_sphinx_sitemap

      - name: Validate benchmarks files
        run: python3 ${OPENVINO_REPO}/docs/scripts/tests/validate_benchmarks.py ${OPENVINO_REPO}/docs/sphinx_setup/_static/benchmarks_files/

      - name: Build docs
        run: |
          cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_DOCS=ON -S ${OPENVINO_REPO} -B ${BUILD_DIR}
          cmake --build ${BUILD_DIR} --target sphinx_docs

      - name: Cache documentation
        id: cache_sphinx_docs
        uses: actions/cache@8b402f58fbc84540c8b491a91e594a4576fec3d7 # v5.0.2
        with:
          path: ${{ env.BUILD_DIR }}/docs/_build/.doctrees
          key: sphinx-docs-cache

      - name: Set PR number
        run: |
          PR_NUMBER=$(echo $GITHUB_REF | awk 'BEGIN { FS = "/" } ; { print $3 }')
          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV

      - name: Upload sphinx.log
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: sphinx_build_log_${{ env.PR_NUMBER }}.log
          path: ${{ env.BUILD_DIR }}/docs/sphinx.log

      - name: Upload docs html
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: openvino_docs_html_${{ env.PR_NUMBER }}
          path: ${{ env.BUILD_DIR }}/docs/_build

      - name: Run Pytest
        run: |
          pytest --sphinx="${BUILD_DIR}/docs/sphinx.log" \
                 --suppress-warnings="${OPENVINO_REPO}/docs/scripts/tests/suppress_warnings.txt" \
                 --confcutdir="${OPENVINO_REPO}/docs/scripts/tests/" \
                 --html="${OPENVINO_REPO}/build/docs/_artifacts/doc-generation.html" \
                 --sphinx-strip="${BUILD_DIR}/docs/sphinx_source" \
                 --xfail="${OPENVINO_REPO}/docs/scripts/tests/xfail.txt" \
                 --self-contained-html ${OPENVINO_REPO}/docs/scripts/tests/test_docs.py

      - name: Upload test results
        if: failure()
        uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
        with:
          name: openvino_docs_pytest
          path: ${{ env.BUILD_DIR }}/docs/_artifacts/