---
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

env:
  PACKAGE_VERSION: ${{ inputs.ansible-package-version }}

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

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

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

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

    - name: Install project requirements
      run: >-
        python -m pip install
        -r tests/requirements.in
        -c tests/requirements.txt
      working-directory: build-directory

    - name: Set the VERSION variable
      run: echo VERSION="${PACKAGE_VERSION}" >> "${GITHUB_ENV}"

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

    - name: Create a tarball with the build contents
      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@v5
      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: |
        curl -X PUT "${{ env.ROOM_URL }}/${TX_ID}" \
             -H "Authorization: Bearer ${{ secrets.DOCS_BOT_TOKEN }}" \
             -H "Content-Type: application/json" \
             -d '{"msgtype": "m.text", "body": "${{ env.FAIL_MESSAGE }}"}'
