docs.yml

name: Docs

on:
  pull_request:
  workflow_dispatch:
  push:
    branches:
      - main

permissions:
  contents: read

env:
  JUSTFILE: ${{ github.workspace }}/pipeline.just

concurrency:
  group: docs-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: true

jobs:
  build:
    name: Build Python API docs
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Load CI versions
        shell: bash
        run: cat "$GITHUB_WORKSPACE/.github/ci-versions.env" >> "$GITHUB_ENV"

      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: ${{ env.CI_RUST }}

      - name: Cache Rust build
        uses: Swatinem/rust-cache@v2

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.CI_PYTHON }}
          cache: pip
          cache-dependency-path: |
            bindings/python/docs/requirements.txt
            bindings/python/pyproject.toml

      - name: Create virtual environment
        run: |
          python -m venv .venv
          echo "VIRTUAL_ENV=$GITHUB_WORKSPACE/.venv" >> "$GITHUB_ENV"
          echo "PYTHON_PATH=$GITHUB_WORKSPACE/.venv/bin/python" >> "$GITHUB_ENV"
          echo "PYO3_PYTHON=$GITHUB_WORKSPACE/.venv/bin/python" >> "$GITHUB_ENV"
          echo "$GITHUB_WORKSPACE/.venv/bin" >> "$GITHUB_PATH"

      - name: Install documentation dependencies
        working-directory: bindings/python
        run: |
          "$PYTHON_PATH" -m pip install --upgrade pip
          "$PYTHON_PATH" -m pip install -r docs/requirements.txt

      - name: Install maturin and Python build dependencies
        run: |
          "$PYTHON_PATH" -m pip install -r requirements.txt

      - name: Setup just
        uses: extractions/setup-just@v3

      - name: Build documentation
        run: just --justfile "$JUSTFILE" build-python-docs

  build-site:
    name: Build docs site
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Load CI versions
        shell: bash
        run: cat "$GITHUB_WORKSPACE/.github/ci-versions.env" >> "$GITHUB_ENV"

      - name: Install Doxygen and Graphviz
        run: |
          sudo apt-get update
          sudo apt-get install -y --no-install-recommends doxygen graphviz

      - name: Setup Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          toolchain: ${{ env.CI_RUST }}
          targets: wasm32-unknown-unknown

      - name: Cache Rust build
        uses: Swatinem/rust-cache@v2

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.CI_NODE }}
          cache: npm
          cache-dependency-path: bindings/js/package-lock.json

      - name: Resolve wasm-bindgen-cli version
        id: wasm-bindgen
        shell: bash
        run: |
          set -euo pipefail
          VERSION="$(
            awk '/^wasm-bindgen[[:space:]]*=/ {
                   match($0, /[0-9]+\.[0-9]+\.[0-9]+/); print substr($0, RSTART, RLENGTH); exit
                 }' bindings/js/Cargo.toml
          )"
          if [[ -z "${VERSION}" ]]; then
            echo "::error::could not resolve the wasm-bindgen version from bindings/js/Cargo.toml"
            exit 1
          fi
          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"

      - name: Install wasm-bindgen-cli
        uses: taiki-e/install-action@v2
        with:
          tool: wasm-bindgen-cli@${{ steps.wasm-bindgen.outputs.version }}

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.CI_PYTHON }}
          cache: pip
          cache-dependency-path: requirements.txt

      - name: Create virtual environment
        run: |
          python -m venv .venv
          echo "VIRTUAL_ENV=$GITHUB_WORKSPACE/.venv" >> "$GITHUB_ENV"
          echo "PYTHON_PATH=$GITHUB_WORKSPACE/.venv/bin/python" >> "$GITHUB_ENV"
          echo "PYO3_PYTHON=$GITHUB_WORKSPACE/.venv/bin/python" >> "$GITHUB_ENV"
          echo "$GITHUB_WORKSPACE/.venv/bin" >> "$GITHUB_PATH"

      - name: Setup just
        uses: extractions/setup-just@v3

      - name: Build documentation site
        run: just --justfile "$JUSTFILE" assemble-docs-site

      # assemble-docs-site writes the complete publishable tree, so the
      # artifact is the site itself: target/docs-site is the only uploaded
      # path and therefore the artifact root, and the deploy job publishes
      # its contents verbatim.
      - name: Upload documentation site
        uses: actions/upload-artifact@v4
        with:
          name: docs-site
          path: target/docs-site
          # The generated references contain dot-prefixed files, which the
          # upload skips by default and the deploy would then publish without.
          include-hidden-files: true
          if-no-files-found: error
          # Long enough to redeploy an existing artifact after a failed deploy.
          retention-days: 7

  deploy:
    name: Deploy docs site to Cloudflare Pages
    runs-on: ubuntu-22.04
    # Publish only from the canonical repository's main branch; never from
    # pull requests or forks (they lack the Cloudflare secrets anyway).
    if: >-
      (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
      && github.ref == 'refs/heads/main'
      && github.repository == 'openpitkit/pit'
    # Only build-site produces what is published; the other doc jobs build
    # references that never reach this site, so they must not gate the deploy.
    needs: [build-site]
    permissions:
      contents: read
      deployments: write
    steps:
      # The artifact carries the whole site, so nothing from the repository
      # is published here; the checkout survives only to supply the pinned
      # CI versions read by the next step.
      - name: Checkout CI versions
        uses: actions/checkout@v4
        with:
          sparse-checkout: .github

      - name: Load CI versions
        shell: bash
        run: cat "$GITHUB_WORKSPACE/.github/ci-versions.env" >> "$GITHUB_ENV"

      - name: Download documentation site
        uses: actions/download-artifact@v4
        with:
          name: docs-site
          path: docs-site

      - name: Check Cloudflare configuration
        env:
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
        run: |
          missing=0
          if [ -z "$CLOUDFLARE_ACCOUNT_ID" ]; then
            echo "::error::CLOUDFLARE_ACCOUNT_ID secret is not configured"
            missing=1
          fi
          if [ -z "$CLOUDFLARE_API_TOKEN" ]; then
            echo "::error::CLOUDFLARE_API_TOKEN secret is not configured"
            missing=1
          fi
          exit "$missing"

      - name: Deploy docs to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          gitHubToken: ${{ secrets.GITHUB_TOKEN }}
          wranglerVersion: ${{ env.CI_WRANGLER }}
          command: >-
            pages deploy docs-site --project-name=openpit-docs