.github/workflows/sphinx-docs.yml

#<!--
#     Licensed to the Apache Software Foundation (ASF) under one
#     or more contributor license agreements.  See the NOTICE file
#     distributed with this work for additional information
#     regarding copyright ownership.  The ASF licenses this file
#     to you under the Apache License, Version 2.0 (the
#     "License"); you may not use this file except in compliance
#     with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#     Unless required by applicable law or agreed to in writing,
#     software distributed under the License is distributed on an
#     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
#     KIND, either express or implied.  See the License for the
#     specific language governing permissions and limitations
#     under the License.
#-->
name: Build Sphinx Documentation

on:
  push:
    branches: [ "main", "update_references"]
    paths:
      - 'docs/**'
      - '.github/workflows/sphinx-docs.yml'
  pull_request:
    branches: [ "main", "update_references" ]
    paths:
      - 'docs/**'
      - '.github/workflows/sphinx-docs.yml'
  workflow_dispatch:

concurrency:
  group: "doc-pages"
  cancel-in-progress: true

jobs:
  build-docs:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v7
      with:
        fetch-depth: 0

    - name: Set up Python 3.12
      uses: actions/setup-python@v7
      with:
        python-version: '3.12'
        cache: 'pip'

    - name: Install system dependencies
      run: |
        sudo apt-get update
        sudo apt-get install -y graphviz

    - name: Upgrade pip and setuptools
      run: |
        python -m pip install --upgrade --no-cache-dir pip setuptools

    - name: Install Sphinx and dependencies
      run: |
        python -m pip install --upgrade --no-cache-dir sphinx sphinx-rtd-theme sphinx-simplepdf
        # python -m pip install --group documentation --upgrade --upgrade-strategy only-if-needed --no-cache-dir
        pip install -e ".[documentation]"

    - name: Build Sphinx documentation
      working-directory: ./docs
      run: |
        # sphinx-build docs -b dirhtml _build
        python -m sphinx -T -W --keep-going -b dirhtml -d _build/doctrees -D language=en . _build/html

    - name: Upload HTML artifact
      uses: actions/upload-artifact@v7
      with:
        name: sphinx-docs-html
        path: docs/_build/html/
        retention-days: 5

    - name: Upload PDF artifact
      uses: actions/upload-artifact@v7
      with:
        name: sphinx-docs-pdf
        path: docs/_build/pdf/
        retention-days: 5

    # NOTE: Deployment to asf-site is now handled by build-site.yml
    # which builds both the landing page and Sphinx docs together.
    # This workflow only builds + uploads artifacts for PR review.