docs.yaml

name: Docs

on:
  push:
    branches: [develop]
  pull_request:
    branches: [main, develop]
  workflow_call:
  workflow_dispatch:
    inputs:
      tag:
        description: The version's tag of the docs to build
        required: true
        type: string
env:
  WORKFLOW_DISPATCH_TAG: ${{ github.event.inputs.tag }}

permissions:
  contents: read

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.tag || github.ref }}
          # NOTE: Fake ternary operator, see https://github.com/actions/runner/issues/409
          fetch-depth: 0  # Fetch all commits and tags, needed for intermediate versions

      - name: Set up Python 3.13
        uses: actions/setup-python@v5
        with:
          python-version: '3.13'
          cache: 'pip'
          cache-dependency-path: |
            docs/requirements.txt
            pyproject.toml

      - name: Upgrade pip
        run: python3 -m pip install --upgrade pip

      - name: Install the documentation dependencies
        run: python3 -m pip install -r docs/requirements.txt

      - name: Install the `galois` package
        run: python3 -m pip install .

      - name: Run Sphinx to build docs
        run: sphinx-build -b dirhtml -v docs/ docs/build/

      # Tarring is needed because upload-artifact does not preserve case sensitivity
      - name: Tar files
        run: tar -czvf docs.tar.gz -C docs/build/ .

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: docs
          path: docs.tar.gz
          retention-days: 30

  publish:
    name: Publish
    needs: build
    # Only publish new docs to GitHub pages if on a pre-release branch or tagged released version
    if: ${{ github.event_name == 'push' || github.event_name == 'workflow_call' || github.event_name == 'workflow_dispatch'}}
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          ref: gh-pages

      - name: Download artifacts
        uses: actions/download-artifact@v4
        with:
          name: docs
          path: .

      - name: Determine folder name
        id: folder
        shell: python
        run: |
          import os
          import re

          github_ref = os.environ.get('GITHUB_REF')
          print("github_ref:", github_ref)

          github_event_name = os.environ.get("GITHUB_EVENT_NAME")
          print("github_event_name:", github_event_name)

          workflow_dispatch_tag = os.environ.get("WORKFLOW_DISPATCH_TAG")
          print("workflow_dispatch_tag:", workflow_dispatch_tag)

          if github_event_name == "push" and github_ref == "refs/heads/develop":
              name = "dev"
          elif github_event_name == "push" and github_ref.startswith("refs/tags/"):
              name = github_ref.split("refs/tags/")[1]
          elif github_event_name == "workflow_dispatch":
              name = workflow_dispatch_tag
          else:
              raise RuntimeError

          with open(os.environ["GITHUB_OUTPUT"], "a") as f:
            f.write(f"name={name}")

      - name: Clear old version folder
        run: |
          rm -rf ${{ steps.folder.outputs.name }}
          mkdir ${{ steps.folder.outputs.name }}

      # Un-tarring is needed because upload-artifact does not preserve case sensitivity
      - name: Untar files
        run: tar -xzvf docs.tar.gz -C ${{ steps.folder.outputs.name }}

      - name: Remove artifacts
        run: rm docs.tar.gz

      - name: Update versions.json file
        shell: python
        run: |
          import json
          import os
          import pathlib
          import re
          from packaging.version import Version, InvalidVersion

          cwd = pathlib.Path.cwd()

          # Gather top-level folders (ignore dotfolders)
          folders = [p.name for p in cwd.iterdir() if p.is_dir() and not p.name.startswith(".")]
          print("folders:", folders)

          # Remove "latest" symlink if present (we will recreate it)
          if "latest" in folders:
              folders.remove("latest")
              os.system("rm -f latest")

          # Identify release folders like v0.4.9, v1.2.3, v0.5.0rc1, etc.
          # Keep it simple: must start with 'v' and be parseable by packaging.version
          releases = []
          others = []

          for name in folders:
              if name.startswith("v"):
                  try:
                      Version(name[1:])  # strip leading 'v'
                      releases.append(name)
                  except InvalidVersion:
                      others.append(name)
              else:
                  others.append(name)

          # Sort releases newest -> oldest
          releases.sort(key=lambda s: Version(s[1:]), reverse=True)

          # Build versions.json entries
          list_of_dicts = []

          # Optionally include "dev" first (if present)
          if "dev" in others:
              list_of_dicts.append({"version": "dev", "title": "dev", "aliases": []})

          latest = None
          for v in releases:
              aliases = []
              if latest is None:
                  latest = v
                  aliases = ["latest"]
                  os.system(f"ln -s {v} latest")
              list_of_dicts.append({"version": v, "title": v, "aliases": aliases})

          print("versions.json:", list_of_dicts)

          with (cwd / "versions.json").open("w") as f:
              json.dump(list_of_dicts, f, indent=4)

      - run: git status

      - run: git diff --stat

      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Deploy ${{ github.sha }}