docs.yml

name: Docs Automation

on:
  push:
    branches: [main]
    paths:
      - "scripts/**"
      - ".github/workflows/docs.yml"
  pull_request:
    branches: [main]
    paths:
      - "scripts/**"
      - ".github/workflows/docs.yml"
  workflow_dispatch:
  workflow_call:

permissions:
  contents: write
  pull-requests: write

jobs:
  discover:
    name: Discover Repositories
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    outputs:
      repos: ${{ steps.repos.outputs.repos }}
    steps:
      - name: Discover source repos
        id: repos
        env:
          GH_TOKEN: ${{ github.token }}
          ORG: ${{ github.repository_owner }}
        run: |
          set -euo pipefail

          RUNNING_REPO="${GITHUB_REPOSITORY#*/}"

          # Convert to lowercase to avoid case-sensitivity mismatches
          RUNNING_REPO="${RUNNING_REPO,,}"
          ORG="${ORG,,}"

          # If running on a library repo, return it and exit early
          if [ "${RUNNING_REPO}" != "${ORG}.github.io" ]; then
            clone_url="https://github.com/${GITHUB_REPOSITORY}.git"
            echo "repos=$(jq -cn --arg name "$RUNNING_REPO" --arg clone_url "$clone_url" '[{name: $name, clone_url: $clone_url}]')" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          tmp="$(mktemp -d)"
          repos_file="$tmp/repos.jsonl"

          gh api --paginate "/orgs/${ORG}/repos" \
            --jq '.[] | select(.archived == false and .disabled == false) | [.name, .clone_url] | @tsv' \
            > "$repos_file"

          found="[]"
          while IFS=$'\t' read -r name clone_url; do
            name_lower="${name,,}"
            [ "${name_lower}" != "${ORG}.github.io" ] || continue

            if gh api "/repos/${ORG}/${name}/contents/types" >/dev/null 2>&1; then
              found="$(jq --arg name "$name" --arg clone_url "$clone_url" \
                '. + [{ "name": $name, "clone_url": $clone_url }]' <<< "$found")"
            fi
          done < "$repos_file"

          echo "repos=$(jq -c . <<< "$found")" >> "$GITHUB_OUTPUT"

  generate:
    name: Generate API Docs (${{ matrix.repo.name }})
    needs: discover
    if: ${{ needs.discover.outputs.repos != '[]' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        repo: ${{ fromJson(needs.discover.outputs.repos) }}
    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v6
        with:
          repository: ${{ github.repository_owner }}/${{ github.repository_owner }}.github.io
          path: _docs

      - name: Checkout source repo
        uses: actions/checkout@v6
        with:
          repository: ${{ github.repository_owner }}/${{ matrix.repo.name }}
          path: _source
          fetch-depth: 1

      - name: Validate types directory
        run: |
          if [ ! -d "_source/types" ]; then
            echo "::error::The 'types' directory does not exist in the source repository: ${{ matrix.repo.name }}"
            exit 1
          fi

      - name: Setup LuaJIT
        uses: leafo/gh-actions-lua@v13
        with:
          luaVersion: "luajit"

      - name: Generate docs
        run: |
          set -euo pipefail

          output_dir="_docs/docs/src/${{ matrix.repo.name }}/api"
          mkdir -p "$output_dir"

          luajit _docs/scripts/generate-api-docs.lua "_source/types" "$output_dir"

      - name: Format docs
        run: npx --yes prettier@3.8.3 --write "_docs/docs/src/${REPO_NAME}/api/*.md" --no-error-on-unmatched-pattern
        env:
          REPO_NAME: ${{ matrix.repo.name }}

      - name: Open docs PR
        uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ secrets.DOCS_TOKEN }}
          path: _docs
          commit-message: "docs(${{ matrix.repo.name }}): generate API docs"
          title: "docs(${{ matrix.repo.name }}): generate API docs"
          body: "Generate and format API docs from `${{ matrix.repo.name }}` LuaLS type annotations."
          branch: "automation/generate-docs-${{ matrix.repo.name }}"
          add-paths: |
            docs/src/${{ matrix.repo.name }}/api