build-package-docs.yaml

---

name: Ansible package docs build
on:
  workflow_dispatch:
    inputs:
      repository-owner:
        description: GitHub account or org that owns the repository
        required: true
        default: ansible
      repository-name:
        description: Name of the GitHub repository
        required: true
        default: ansible-documentation
      repository-branch:
        description: Branch, tag, or commit SHA
        required: true
        default: devel
      ansible-package-version:
        type: choice
        description: Ansible community package version
        required: true
        default: devel
        options:
        - devel
        - '11'
        - '10'
        - '9'
      deploy:
        type: boolean
        description: Deploy the build
        required: true
      deployment-environment:
        type: choice
        description: Deployment environment
        required: true
        default: test
        options:
        - production
        - test

env:
  PACKAGE_VERSION: ${{ github.event.inputs.ansible-package-version || 'devel' }}

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

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

    - 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 COLLECTION_LIST variable
      if: env.PACKAGE_VERSION != 'devel'
      run: >-
        echo COLLECTION_LIST='"${PACKAGE_VERSION}"'
        >> "${GITHUB_ENV}"

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

    - name: Build the Ansible community package docs
      run: make webdocs ANSIBLE_VERSION="${COLLECTION_LIST}"
      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@v4
      with:
        name: package-docs-build
        path: build-directory/docs/docsite/ansible-package-docs-html-*.tar.gz
        retention-days: 7

  check-deploy:
    if: github.event_name == 'workflow_dispatch' && github.event.inputs.deploy == 'true'
    needs: build-package-docs
    runs-on: ubuntu-latest
    steps:
    - name: Log the workflow inputs if deployed
      run: |
        echo "## Deployment details :shipit:" >> "${GITHUB_STEP_SUMMARY}"
        echo "Publish to: ${{ github.event.inputs.deployment-environment }}" >> "${GITHUB_STEP_SUMMARY}"
        echo "Package version: ${{ github.event.inputs.ansible-package-version }}"  >> "${GITHUB_STEP_SUMMARY}"
        echo "Owner: ${{ github.event.inputs.repository-owner }}" >> "${GITHUB_STEP_SUMMARY}"
        echo "Branch: ${{ github.event.inputs.repository-branch }}" >> "${GITHUB_STEP_SUMMARY}"

  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 }}"}'

  deploy-package-docs:
    needs:
      - check-deploy
    runs-on: ubuntu-latest
    environment:
      name: deploy-package-docs
      url: ${{ env.ENV_URL }}
    env:
      TARGET: ${{ github.event.inputs.deployment-environment }}
      DEST_REPO: ansible-community/package-doc-builds
      USER_EMAIL: "41898282+github-actions[bot]@users.noreply.github.com"
      USER_NAME: "github-actions[bot]"
    steps:
    - name: Download the build archive
      uses: actions/download-artifact@v4
      with:
        name: package-docs-build

    - name: Extract the tarball
      run: >-
        tar -xvzf
        ansible-package-docs-html-*.tar.gz
        --one-top-level

    - name: Set the production branch and url
      if: env.TARGET == 'production'
      env:
        BRANCH_NAME: ${{ github.event.inputs.ansible-package-version }}
        PROD_URL: https://ansible.readthedocs.io/projects/ansible
      run: |
        echo "BRANCH=${BRANCH_NAME}" >> "${GITHUB_ENV}"
        echo "ENV_URL=${PROD_URL}/${BRANCH_NAME}" >> "${GITHUB_ENV}"

    - name: Set the test branch and url
      if: env.TARGET == 'test'
      env:
        TEST_URL: https://ansible-community.github.io/package-doc-builds
      run: |
        echo "BRANCH=gh-pages" >> "${GITHUB_ENV}"
        echo "ENV_URL=${TEST_URL}" >> "${GITHUB_ENV}"

    - name: Checkout the deploy directory
      uses: actions/checkout@v4
      with:
        repository: ${{ env.DEST_REPO }}
        ref: ${{ env.BRANCH }}
        path: deploy-directory
        fetch-depth: 0
        ssh-key: ${{ secrets.DEPLOY_DOC_BUILD }}
        persist-credentials: true

    - name: Copy the generated HTML and assets for production
      run: >-
        rsync -av --delete --mkpath
        ansible-package-docs-html-*/
        deploy-directory/docs

    - name: Create a norobots.txt file for the test site
      if: env.TARGET == 'test'
      run: |
        touch norobots.txt
        echo "User-agent: *" > norobots.txt
        echo "Disallow: /" >> norobots.txt
      working-directory: deploy-directory/docs

    - name: Configure the git user
      run: |
        git config --local user.email "${USER_EMAIL}"
        git config --local user.name "${USER_NAME}"
      working-directory: deploy-directory

    - name: Git add the generated HTML and assets
      run: git add ./docs --all --force
      working-directory: deploy-directory

    - name: Commit generated HTML and assets
      run: >-
        git diff-index --quiet HEAD ||
        git commit -m "Push docs build $(date '+%Y-%m-%d')-${{
          github.run_id
        }}-${{
           github.run_number
        }}-${{
          github.run_attempt
        }}"
      working-directory: deploy-directory

    - name: Push build to deploy repository
      run: git push origin
      working-directory: deploy-directory