docs.yml

name: Build and deploy documentation

on:
  push:
    branches:
      - master
      - develop
      - v1.5
    paths:
      - 'docs/**'
      - '.github/workflows/docs.yml'
  pull_request:
    paths:
      - 'docs/**'
      - '.github/workflows/docs.yml'
  workflow_dispatch:

# Allow the deploy job to publish to GitHub Pages.
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment; do not cancel an in-progress
# production deploy, but skip queued runs in between.
concurrency:
  group: pages
  cancel-in-progress: false

# Versions published in the switcher. The first entry is treated as the
# default (the site root redirects to it). Keep PAGES_VERSIONS, the
# versions.json manifest, and the landing redirect below in sync.
#
# Languages are NOT configured here: each branch declares its own set in
# docs/languages.txt (first entry = default). A branch that ships that file is
# published with a per-language layout (<version>/<lang>/...) plus a
# per-version languages.json the language switcher reads; a branch without it
# keeps the legacy single-language layout (<version>/...). This keeps older,
# English-only branches working unchanged.
env:
  PAGES_VERSIONS: 'master v1.5'
  PAGES_DEFAULT: 'master'

jobs:
  build:
    name: Build HTML
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash  # explicit: the manifest step relies on bash word-splitting
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # need every documentation branch for the multi-version build

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          # Sphinx 9 (required by the breeze theme on this branch) needs
          # Python >= 3.12; the older branches' pinned Sphinx also runs fine
          # on 3.12 thanks to the per-version venvs below.
          python-version: '3.12'

      # --- Pull request: validate that the changed docs build, do not deploy ---
      - name: Build (pull request validation)
        if: github.event_name == 'pull_request'
        run: |
          set -euo pipefail
          python -m venv "$RUNNER_TEMP/venv-pr"
          "$RUNNER_TEMP/venv-pr/bin/pip" install --upgrade pip
          "$RUNNER_TEMP/venv-pr/bin/pip" install -r docs/requirements.txt
          # Build every language this branch declares (validates the gettext
          # catalogs too), or just English when no languages.txt is present.
          if [ -f docs/languages.txt ]; then
            langs=$(grep -vE '^[[:space:]]*#|^[[:space:]]*$' docs/languages.txt)
          else
            langs=en
          fi
          for lang in $langs; do
            echo "::group::Build PR ($lang)"
            DOCS_LANGUAGE="$lang" "$RUNNER_TEMP/venv-pr/bin/sphinx-build" -b html \
              docs/source "$RUNNER_TEMP/_site_pr/$lang"
            echo "::endgroup::"
          done

      # --- Push / manual run: build every version and assemble the site ---
      - name: Configure GitHub Pages
        if: github.event_name != 'pull_request'
        uses: actions/configure-pages@v5
        with:
          # Switch the Pages source to "GitHub Actions" (off the legacy
          # gh-pages branch) on the first run, and enable Pages if needed.
          enablement: true

      - name: Fetch documentation branches
        if: github.event_name != 'pull_request'
        run: |
          set -euo pipefail
          for v in $PAGES_VERSIONS; do
            git fetch --no-tags origin "+refs/heads/$v:refs/remotes/origin/$v"
          done

      # TeX Live for the per-language PDFs built into the site below. Covers
      # pdflatex (English) and LuaLaTeX + LuaTeX-ja (Japanese), plus GNU
      # FreeFont for the Latin body text and Harano Aji for Japanese.
      - name: Install TeX Live (PDF build)
        if: github.event_name != 'pull_request'
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            latexmk \
            texlive-luatex \
            texlive-latex-recommended \
            texlive-latex-extra \
            texlive-fonts-recommended \
            texlive-lang-japanese \
            tex-gyre \
            fonts-freefont-otf

      - name: Build all versions
        if: github.event_name != 'pull_request'
        run: |
          set -euo pipefail
          rm -rf _site
          mkdir -p _site
          for v in $PAGES_VERSIONS; do
            echo "::group::Build $v"
            worktree="$RUNNER_TEMP/wt-$v"
            venv="$RUNNER_TEMP/venv-$v"
            git worktree add --force "$worktree" "origin/$v"
            # Each branch is built with its own pinned requirements, so a venv
            # per version keeps incompatible Sphinx/theme versions isolated.
            python -m venv "$venv"
            "$venv/bin/pip" install --upgrade pip
            "$venv/bin/pip" install -r "$worktree/docs/requirements.txt"
            if [ -f "$worktree/docs/languages.txt" ]; then
              # New layout: one subdirectory per language, a languages.json
              # manifest, and a landing page redirecting to the default language.
              langs=$(grep -vE '^[[:space:]]*#|^[[:space:]]*$' "$worktree/docs/languages.txt")
              default_lang=$(printf '%s\n' $langs | head -n1)
              for lang in $langs; do
                DOCS_VERSION="$v" DOCS_LANGUAGE="$lang" "$venv/bin/sphinx-build" \
                  -b html "$worktree/docs/source" "_site/$v/$lang"
                # Build the PDF next to that language's HTML so the in-page
                # download link can reach it at <version>/<lang>/ALAMODE.pdf.
                # Non-fatal: a PDF failure must never block the HTML deploy --
                # the link self-hides when the PDF is absent.
                pdfdir="$RUNNER_TEMP/pdf-$v-$lang"
                if DOCS_VERSION="$v" DOCS_LANGUAGE="$lang" "$venv/bin/sphinx-build" \
                     -b latex "$worktree/docs/source" "$pdfdir" \
                   && make -C "$pdfdir" all-pdf \
                        LATEXMKOPTS="-interaction=nonstopmode -halt-on-error"; then
                  cp "$pdfdir/ALAMODE.pdf" "_site/$v/$lang/ALAMODE.pdf"
                else
                  echo "::warning::PDF build failed for $v/$lang; publishing HTML without it."
                fi
              done
              json=$(printf '"%s",' $langs); json="[${json%,}]"
              printf '%s\n' "$json" > "_site/$v/languages.json"
              {
                echo '<!DOCTYPE html>'
                echo '<html lang="en"><head><meta charset="utf-8">'
                echo "<meta http-equiv=\"refresh\" content=\"0; url=./$default_lang/\">"
                echo "<link rel=\"canonical\" href=\"./$default_lang/\">"
                echo '<title>ALAMODE documentation</title></head>'
                echo "<body>Redirecting to the <a href=\"./$default_lang/\">documentation</a>&hellip;</body></html>"
              } > "_site/$v/index.html"
            else
              # Legacy single-language layout (English only).
              DOCS_VERSION="$v" "$venv/bin/sphinx-build" -b html \
                "$worktree/docs/source" "_site/$v"
            fi
            git worktree remove --force "$worktree"
            echo "::endgroup::"
          done

      - name: Generate manifest and landing page
        if: github.event_name != 'pull_request'
        run: |
          set -euo pipefail
          # versions.json: the manifest the version switcher reads at runtime.
          json=$(printf '"%s",' $PAGES_VERSIONS); json="[${json%,}]"
          printf '%s\n' "$json" > _site/versions.json
          # Root landing page: redirect to the default version (whose own
          # index then redirects to its default language, if it has several).
          {
            echo '<!DOCTYPE html>'
            echo '<html lang="en"><head><meta charset="utf-8">'
            echo "<meta http-equiv=\"refresh\" content=\"0; url=./$PAGES_DEFAULT/\">"
            echo "<link rel=\"canonical\" href=\"./$PAGES_DEFAULT/\">"
            echo '<title>ALAMODE documentation</title></head>'
            echo "<body>Redirecting to the <a href=\"./$PAGES_DEFAULT/\">$PAGES_DEFAULT documentation</a>&hellip;</body></html>"
          } > _site/index.html
          # Defensive: GitHub Actions Pages does not run Jekyll, but this keeps
          # underscore-prefixed Sphinx dirs (_static, _sources) safe anywhere.
          touch _site/.nojekyll

      - name: Upload artifact
        if: github.event_name != 'pull_request'
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

  validate-pdf:
    name: Validate PDFs (pull request)
    # PR-only: on push the build job builds and publishes the per-language PDFs
    # into the site. Here we just confirm that every declared language's PDF
    # compiles before merge. Fatal -- a broken PDF fails the check.
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          # Sphinx 9 (required by the breeze theme on this branch) needs
          # Python >= 3.12; the older branches' pinned Sphinx also runs fine
          # on 3.12 thanks to the per-version venvs below.
          python-version: '3.12'

      # pdflatex (English) and LuaLaTeX + LuaTeX-ja (ltjsbook class, Harano Aji
      # fonts) for Japanese, plus GNU FreeFont for the Latin body text.
      - name: Install TeX Live (PDF build)
        run: |
          set -euo pipefail
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends \
            latexmk \
            texlive-luatex \
            texlive-latex-recommended \
            texlive-latex-extra \
            texlive-fonts-recommended \
            texlive-lang-japanese \
            tex-gyre \
            fonts-freefont-otf

      - name: Build PDFs for all declared languages
        run: |
          set -euo pipefail
          python -m venv "$RUNNER_TEMP/venv-pdf"
          "$RUNNER_TEMP/venv-pdf/bin/pip" install --upgrade pip
          "$RUNNER_TEMP/venv-pdf/bin/pip" install -r docs/requirements.txt
          if [ -f docs/languages.txt ]; then
            langs=$(grep -vE '^[[:space:]]*#|^[[:space:]]*$' docs/languages.txt)
          else
            langs=en
          fi
          for lang in $langs; do
            echo "::group::PDF ($lang)"
            pdfdir="$RUNNER_TEMP/latex-$lang"
            DOCS_LANGUAGE="$lang" "$RUNNER_TEMP/venv-pdf/bin/sphinx-build" -b latex \
              docs/source "$pdfdir"
            # all-pdf drives latexmk; the generated latexmkrc selects the right
            # engine (pdflatex for en, lualatex for ja). Halt on first error.
            make -C "$pdfdir" all-pdf \
              LATEXMKOPTS="-interaction=nonstopmode -halt-on-error"
            cp "$pdfdir/ALAMODE.pdf" "$RUNNER_TEMP/ALAMODE-$lang.pdf"
            echo "::endgroup::"
          done

      - name: Upload validated PDFs
        uses: actions/upload-artifact@v4
        with:
          name: alamode-pdfs
          path: ${{ runner.temp }}/ALAMODE-*.pdf
          if-no-files-found: error

  deploy:
    name: Deploy to GitHub Pages
    # Never publish from pull requests.
    if: github.event_name != 'pull_request'
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
        with:
          # Keep the deployment polling window at the action's allowed
          # maximum (values above 600000 ms are clamped with a warning).
          # Transient "Deployment failed, try again later" errors are not
          # timeout-related; just re-run the failed deploy job for those.
          timeout: 600000  # 10 minutes (the maximum), in milliseconds