---
name: Build docs

"on":
  workflow_call:
    inputs:
      repository-owner:
        description: GitHub account or org that owns the repository
        type: string
        required: false
        default: ansible
      repository-name:
        description: Name of the GitHub repository
        type: string
        required: false
        default: ansible-documentation
      repository-branch:
        description: Branch, tag, or commit SHA
        type: string
        required: false
        default: devel
      ansible-package-version:
        type: string
        description: Ansible community package version
        required: false
        default: devel
      generate-redirects:
        description: Generate page redirects
        type: boolean
        default: true
    secrets:
      DOCS_BOT_TOKEN:
        required: true

jobs:
  build-package-docs:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout Ansible documentation
      uses: actions/checkout@v6
      with:
        repository: >-
          ${{
            inputs.repository-owner
          }}/${{
            inputs.repository-name
          }}
        ref: ${{ inputs.repository-branch }}
        path: build-directory
        persist-credentials: false

    - name: Setup nox
      uses: wntrblm/nox@2026.02.09

    - name: Output Python info
      run: python --version --version && which python

    - name: Graft ansible-core
      run: nox -s clone-core
      working-directory: build-directory

    - name: Build the Ansible community package docs
      env:
        PACKAGE_VERSION: >-
          ${{
            inputs.ansible-package-version != 'devel'
            && inputs.ansible-package-version
            || ''
          }}
      run: >-
        nox -e make -- webdocs ANSIBLE_VERSION="${PACKAGE_VERSION}" ${{
          inputs.generate-redirects && 'EXTRA_TAGS="-t redirects"' || ''
        }}
      working-directory: build-directory

    - name: Create a tarball with the build contents
      env:
        PACKAGE_VERSION: "${{ inputs.ansible-package-version }}"
      run: >-
        tar -czvf
        ansible-package-docs-html-"${PACKAGE_VERSION}"-"$(date '+%Y-%m-%d')"-${{
          github.run_id
        }}-${{
          github.run_number
        }}-${{
          github.run_attempt
        }}.tar.gz
        --directory=_build/html/ .
      working-directory: build-directory/docs/docsite

    - name: Create a downloadable archive that contains the tarball
      uses: actions/upload-artifact@v7
      with:
        name: package-docs-build
        path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz
        retention-days: 7

  notify-build-failures:
    if: failure()
    needs: build-package-docs
    runs-on: ubuntu-latest
    env:
      ROOM_URL: https://ansible-accounts.ems.host/_matrix/client/v3/rooms/!HJtetIFWYEIDBOXxFE:libera.chat/send/m.room.message
      FAIL_MESSAGE: >-
          Oh no! A community package docs build has failed.
          Check this workflow run to see what went wrong:
          https://github.com/ansible/ansible-documentation/actions/runs/${{ github.run_id }}
          @orandon @samccann
    steps:
    - name: Set a transaction ID
      run: echo "TX_ID=$(date +%s)" >> "${GITHUB_ENV}"

    - name: Notify the DaWGs in Matrix
      run: |
        body="$(python3 -c '
        import json
        import os
        import sys

        json.dump({
          "msgtype": "m.text",
          "body": os.environ["FAIL_MESSAGE"],
        }, sys.stdout)'
        )"
        curl -X PUT "${ROOM_URL}/${TX_ID}" \
             -H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \
             -H "Content-Type: application/json" \
             -d "${body}"
