docs.yml

# Docs build + deploy for both mirrors of this repo. Target is chosen at runtime
# from github.server_url:
#   * github.com -> versioned GitHub Pages (mike)
#   * otherwise  -> an internal docs host (static upload)
# Internal host details come from repo variables (DOCS_HOST / DOCS_RESOLVE_IP),
# which are empty on github.com, so that path is skipped and nothing
# environment-specific is committed.
name: Docs

on:
  push:
    branches: [main, master]
  pull_request:
    types: [opened, synchronize, reopened, closed]
  workflow_dispatch:

permissions:
  contents: write   # mike pushes the gh-pages branch

concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true

env:
  DOCS_HOST: ${{ vars.DOCS_HOST }}
  DOCS_RESOLVE_IP: ${{ vars.DOCS_RESOLVE_IP }}

jobs:
  deploy:
    if: >-
      github.event.action != 'closed' &&
      (github.event_name != 'pull_request' ||
       github.event.pull_request.head.repo.full_name == github.repository)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip uv
          uv sync --group docs --extra ha --extra api

      - name: Prepare docs inputs
        run: |
          printf '{"commit":"%s"}\n' "$(git rev-parse --short HEAD)" > docs/build-info.json
          uv run python scripts/ci/generate_config_schema.py || true
          cp configs/app.schema.json docs/app.schema.json || true
          # Refresh the REST API spec; the committed docs/openapi.json serves
          # as fallback when the API app is not importable here.
          uv run python scripts/ci/generate_openapi_spec.py || true

      # --- github.com: versioned GitHub Pages via mike ---
      - name: Configure git (mike)
        if: github.server_url == 'https://github.com'
        run: |
          git config user.name  "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

      - name: Publish to GitHub Pages
        if: github.server_url == 'https://github.com' && github.ref_name == github.event.repository.default_branch
        run: |
          # Version label is derived from the branch that was pushed, so the
          # same workflow publishes "master" on the GitHub mirror and "main"
          # on the Gitea origin without hardcoding either name.
          uv run mike deploy --push --update-aliases "${{ github.ref_name }}" latest --alias-type copy
          uv run mike set-default --push latest

      - name: Publish PR preview to GitHub Pages
        if: >-
          github.server_url == 'https://github.com' &&
          github.event_name == 'pull_request' &&
          github.event.pull_request.head.repo.full_name == github.repository &&
          contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.pull_request.author_association) &&
          !contains(github.actor, '[bot]')
        run: uv run mike deploy --push "pr-${{ github.event.pull_request.number }}"

      # --- internal docs host: single version, static upload ---
      - name: Publish to internal docs host
        if: github.server_url != 'https://github.com'
        run: |
          slug="assistant"
          [ "${{ github.event_name }}" = "pull_request" ] && slug="assistant-pr-${{ github.event.pull_request.number }}"
          sed -i "s|^site_url:.*|site_url: https://${DOCS_HOST}/${slug}/|" mkdocs.yml
          uv run python -m mkdocs build -d site
          tar -C site -cf site.tar .
          curl -fsS -k --retry 5 --retry-all-errors --retry-delay 4 --max-time 180 \
            --resolve "${DOCS_HOST}:443:${DOCS_RESOLVE_IP}" \
            -X PUT -H 'Content-Type: application/x-tar' --data-binary @site.tar \
            "https://${DOCS_HOST}/${slug}/"

  cleanup:
    # Remove a PR preview from the internal docs host when the PR closes.
    # (GitHub Pages / mike PR cleanup lives in docs-cleanup.yml.)
    if: >-
      github.server_url != 'https://github.com' &&
      github.event_name == 'pull_request' &&
      github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Remove PR preview
        run: |
          curl -fsS -k --retry 3 --retry-all-errors --retry-delay 4 \
            --resolve "${DOCS_HOST}:443:${DOCS_RESOLVE_IP}" \
            -X DELETE "https://${DOCS_HOST}/assistant-pr-${{ github.event.pull_request.number }}/" || true