dls-build-documentation.yaml

name: "[DLS] Documentation PR workflow"
run-name: "[DLS] Documentation PR workflow (by @${{ github.actor }} via ${{ github.event_name }})"
on:
  push:
    branches:
      - 'main'
    paths:
      - 'docs/**'
  pull_request:
    paths:
      - 'docs/**'
permissions: {}

jobs:
  build-docs:
    name: Build DL Streamer documentation
    runs-on: dlstreamer
    permissions:
      contents: read
    steps:
      - name: Check out dlstreamer repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #6.0.2
        with:
          persist-credentials: false

      - name: Run build script
        run: |
          ./docs/build_html.sh "actions-gh-pages:latest" gh-pages
      - name: Documentation build summary
        if: always()
        run: |
          summary_content=""
          # Check if index.html for documentation exists
          index_file_path='./docs/build-html/index.html'
          if [ -f "$index_file_path" ]; then
            result="Documentation built: YES :white_check_mark:"
          else
            result="Documentation built: NO :x:"
          fi
          echo "$result"
          summary_content+="$result\n"
          # Check broken links in linkcheck
          linkcheck_file_path='./docs/build-linkcheck/output.txt'
          broken_count=$(grep -o '\[broken\]' "$linkcheck_file_path" | wc -l)
          if [ "$broken_count" -eq 0 ]; then
            result="Broken links: $broken_count :white_check_mark:"
          else
            result="Broken links: $broken_count :x:"
          fi
          echo "$result"
          summary_content+="$result\n"
          # Spelling
          result="Spelling: check report from artifacts"
          echo "$result"
          summary_content+="$result\n"
          echo "### Building with Sphinx results" >> $GITHUB_STEP_SUMMARY
          echo -e "$summary_content" >> $GITHUB_STEP_SUMMARY
      - name: Check specific links
        if: always()
        run: |
          cd ./docs
          python3 ./scripts/specific_links_checker.py 2>&1 | tee specific_links_checker_report.txt
          summary=$(grep -E '✅ All links are working\.|❌ [0-9]+ broken link\(s\)' specific_links_checker_report.txt | tail -n 1)
          echo "### Extra links checker" >> $GITHUB_STEP_SUMMARY
          echo "$summary" >> $GITHUB_STEP_SUMMARY
      - name: Upload linkcheck report
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f #7.0.0
        if: always()
        with:
          name: docs_linkcheck_report
          path: ./docs/build-linkcheck/

      - name: Upload specific links checker report
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f #7.0.0
        if: always()
        with:
          name: docs_specific_links_checker_report
          path: ./docs/specific_links_checker_report.txt

      - name: Upload spelling report
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f #7.0.0
        if: always()
        with:
          name: docs_spelling_report
          path: ./docs/build-spelling/

      - name: Upload pages
        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f #7.0.0
        if: always()
        with:
          name: docs_site
          path: ./docs/build-html

      - name: Clean up
        if: always()
        run: rm -rf "$GITHUB_WORKSPACE"/*