name: Build documentation for offline usage
on:
  workflow_dispatch:
  schedule:
    # Every week on Monday at midnight (UTC).
    # This keeps the generated HTML documentation fresh.
    - cron: '0 0 * * 1'

jobs:
  build:
    # Don't run scheduled runs on forks unless the CI_OFFLINE_DOCS_CRON variable is set to 'true'.
    # Manual runs can still be triggered as normal.
    if: ${{ github.repository_owner == 'godotengine' || github.event_name != 'schedule' || vars.CI_OFFLINE_DOCS_CRON == 'true' }}
    runs-on: ubuntu-24.04
    timeout-minutes: 180
    strategy:
      max-parallel: 1
      fail-fast: false
      matrix:
        branch:
          - master
          - stable
          - 3.6
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ matrix.branch }}

      - name: Get Python version
        id: pythonv
        run: |
          echo "PYTHON_VERSION=$(python --version)" >> $GITHUB_OUTPUT

      - name: Restore cached virtualenv
        uses: actions/cache/restore@v5
        with:
          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
          path: .venv

      - name: Install dependencies
        run: |
          python -m venv .venv
          source .venv/bin/activate
          python -m pip install -r requirements.txt
          echo "$VIRTUAL_ENV/bin" >> $GITHUB_PATH
          echo "VIRTUAL_ENV=$VIRTUAL_ENV" >> $GITHUB_ENV
          sudo apt update
          sudo apt install parallel libwebp7 imagemagick

      - name: Save virtualenv cache
        uses: actions/cache/save@v5
        with:
          key: venv-${{ runner.os }}-${{ steps.pythonv.outputs.PYTHON_VERSION }}-${{ hashFiles('requirements.txt') }}
          path: .venv

      - name: Sphinx - Build HTML
        run: make SPHINXOPTS='--color -j 4' html

      - uses: actions/upload-artifact@v6
        with:
          name: godot-docs-html-${{ matrix.branch }}
          path: _build/html
          # Keep the current build and the previous build (in case a scheduled build failed).
          # This makes it more likely to have at least one successful build available at all times.
          retention-days: 15

      - name: Sphinx - Build ePub
        run: |
          # Convert WebP images to PNG and replace references, so that ePub readers can display those images.
          # The ePub 3.0 specification has WebP support, but it's not widely supported by apps and e-readers yet.
          shopt -s globstar nullglob
          parallel --will-cite convert {} {.}.png ::: {about,community,contributing,getting_started,img,tutorials}/**/*.webp
          parallel --will-cite sed -i "s/\\.webp$/\\.png/g" ::: {about,community,contributing,getting_started,tutorials}/**/*.rst

          # Remove banners at the top of each page when building `latest`.
          sed -i 's/"godot_is_latest": True/"godot_is_latest": False/' conf.py
          sed -i 's/"godot_show_article_status": True/"godot_show_article_status": False/' conf.py

          make SPHINXOPTS='--color -j 4' epub

      - uses: actions/upload-artifact@v6
        with:
          name: godot-docs-epub-${{ matrix.branch }}
          path: _build/epub/GodotEngine.epub
          # Keep the current build and the previous build (in case a scheduled build failed).
          # This makes it more likely to have at least one successful build available at all times.
          retention-days: 15