ansible-documentation.yml

---
name: Ansible Documentation
concurrency:
  group: ansible-documentation-${{ github.head_ref }}
  cancel-in-progress: true
on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed

permissions: {}

jobs:
  # Validation job runs a strict build to ensure it will fail CI on any mistakes.
  validate:
    permissions:
      contents: read
    name: validate
    if: github.event.action != 'closed'
    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@f724ea35f2f4f14a18c45ad363ffa5f76eabeec9  # main
    with:
      collection-name: hachyderm.general
      artifact-upload: false
      init-lenient: false
      init-fail-on-error: true
      build-ref: refs/pull/${{ github.event.number }}/merge

  # Run Ansible Docsmith to check if README files are up-to-date
  docsmith:
    runs-on: ubuntu-latest
    name: docsmith
    if: github.event.action != 'closed'
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          persist-credentials: false

      - name: Install Python
        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6
        with:
          python-version: "3.13"

      - name: Install ansible-docsmith
        run: |
          python -m pip install --upgrade pip
          pip install \
            ansible-docsmith==2.0.0

      - name: Run ansible-docsmith
        run: |
          for role_dir in roles/* ; do
            ansible-docsmith generate $role_dir
          done

      - name: Check if documentation needs to be updated
        run: |
          set -e
          git diff > diff.txt
          CHANGES=$(wc -l diff.txt | awk '{ print $1 }')
          echo "Number of changes: ${CHANGES}"
          if [ ${CHANGES} -gt 0 ] ; then
            echo ""
            cat diff.txt
            echo ""
            echo "Fix with the following command:"
            echo ""
            echo "run ansible-docsmith generate ${role_dir}"
            exit 1
          fi

  # The build job runs with the most lenient settings to ensure the best chance of getting
  # a rendered docsite that can be looked at.
  build:
    permissions:
      contents: read
    needs:
      - validate
      - docsmith
    name: build
    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-pr.yml@f724ea35f2f4f14a18c45ad363ffa5f76eabeec9  # main
    with:
      collection-name: hachyderm.general
      init-project: Hachyderm General Collection
      init-copyright: Hachyderm contributors
      init-title: Hachyderm General Collection Documentation
      init-html-short-title: Hachyderm General Collection Documentation
      init-extra-html-theme-options: |
        documentation_home_url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr/${{ github.event.number }}
      squash-hierarchy: true
      init-lenient: true
      init-fail-on-error: true

  publish:
    # use to prevent running on forks
    if: github.repository == 'hachyderm/ansible'
    permissions:
      contents: write
      pages: write
      id-token: write
    needs:
      - build
    name: publish PR preview
    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@f724ea35f2f4f14a18c45ad363ffa5f76eabeec9  # main
    with:
      artifact-name: ${{ needs.build.outputs.artifact-name }}
      action: publish
      publish-gh-pages-branch: true
    secrets:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  comment:
    permissions:
      pull-requests: write
    runs-on: ubuntu-latest
    needs:
      - build
      - publish
    name: comment
    steps:
      - name: PR comment
        uses: ansible-community/github-docs-build/actions/ansible-docs-build-comment@f724ea35f2f4f14a18c45ad363ffa5f76eabeec9  # main
        with:
          body-includes: '## Docs Build'
          reactions: heart
          action: ${{ needs.build.outputs.changed != 'true' && 'remove' || '' }}
          on-closed-action: remove
          on-merged-body: |
            ## Documentation 📝

            Thank you for contribution!✨

            This PR has been merged and the docs are now incorporated into `main`:
            ${{ env.GHP_BASE_URL }}/branch/main
          body: |
            ## Documentation 📝

            Thank you for contribution!✨

            The docs for **this PR** have been published here:
            https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr/${{ github.event.number }}

            You can compare to the docs for the `main` branch here:
            https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/branch/main

            The docsite for **this PR** is also available for download as an artifact from this run:
            ${{ needs.build.outputs.artifact-url }}

            File changes:

            ${{ needs.build.outputs.diff-files-rendered }}

            ${{ needs.build.outputs.diff-rendered }}

  cleanup:
    # use to prevent running on forks
    if: github.repository == 'hachyderm/ansible' && github.event.action == 'closed'
    permissions:
      contents: write
      pages: write
      id-token: write
    name: cleanup PR preview
    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@f724ea35f2f4f14a18c45ad363ffa5f76eabeec9  # main
    with:
      artifact-name: ${{ needs.build.outputs.artifact-name }}
      action: teardown
      publish-gh-pages-branch: true
    secrets:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}