add some sample workflows

samples/README.md

@@ -0,0 +1,9 @@
+# Samples
+
+These are samples of workflows you can add to your repository to use the actions and workflows in this repository, to build Ansible docs for your collection.
+
+They are mostly ready to go, but can be customized to your needs. See the [wiki pages](https://github.com/ansible-community/github-docs-build/wiki) to browse the full options for each workflow and action.
+
+The shared workflows in this repository make use of the actions in this repository, and you can use those reusable workflows as-is, or use them as a basis for creating your own workflows that do things a bit differently.
+
+Your repository's workflow can combine jobs that use reusable workflows, and traditional job definitions with your own steps, so there is a lot of flexibility to be had. The workflows and actions here are meant to be modular in that way.

samples/pr-build-and-comment.yml

@@ -0,0 +1,80 @@
+name: Collection Docs
+concurrency:
+  group: docs-pr-${{ github.head_ref }}
+  cancel-in-progress: true
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, closed]
+
+jobs:
+  # Validation job runs a strict build to ensure it will fail CI on any mistakes.
+  validate-docs:
+    permissions:
+      contents: read
+    name: Validate Ansible Docs
+    if: github.event.action != 'closed'
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@main
+    with:
+      artifact-upload: false
+      init-lenient: false
+      init-fail-on-error: true
+      build-ref: refs/pull/${{ github.event.number }}/merge
+
+  # 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-docs:
+    permissions:
+      contents: read
+    name: Build Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-pr.yml@main
+    with:
+      init-lenient: true
+      init-fail-on-error: false
+
+  publish-docs-gh-pages:
+    # use to prevent running on forks
+    if: github.repository == 'repo_owner/repo_name'
+    permissions:
+      contents: write
+    needs: [build-docs]
+    name: Publish Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
+    with:
+      artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
+      action: ${{ (github.event.action == 'closed' || needs.build-docs.outputs.changed != 'true') && 'teardown' || 'publish' }}
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  comment:
+    permissions:
+      pull-requests: write
+    runs-on: ubuntu-latest
+    needs: [build-docs]
+    name: PR comments
+    steps:
+      - name: PR comment
+        uses: ansible-community/github-docs-build/actions/ansible-docs-build-comment@main
+        with:
+          body-includes: '## Docs Build'
+          reactions: heart
+          action: ${{ needs.build-docs.outputs.changed != 'true' && 'remove' || '' }}
+          on-closed-action: remove
+          on-merged-body: |
+            ## Docs Build 📝
+
+            Thank you for contribution!✨
+
+            This PR has been merged and the docs are now incorporated into `main`.
+          body: |
+            ## Docs Build 📝
+
+            Thank you for contribution!✨
+
+            The docsite for **this PR** is available for download as an artifact from this run:
+            ${{ needs.build-docs.outputs.artifact-url }}
+
+            File changes:
+
+            ${{ needs.build-docs.outputs.diff-files-rendered }}
+
+            ${{ needs.build-docs.outputs.diff-rendered }}

samples/pr-with-publish-to-gh-pages.yml

@@ -0,0 +1,91 @@
+name: Collection Docs
+concurrency:
+  group: docs-pr-${{ github.head_ref }}
+  cancel-in-progress: true
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, closed]
+
+env:
+  GHP_BASE_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
+
+jobs:
+  # Validation job runs a strict build to ensure it will fail CI on any mistakes.
+  validate-docs:
+    permissions:
+      contents: read
+    name: Validate Ansible Docs
+    if: github.event.action != 'closed'
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@main
+    with:
+      artifact-upload: false
+      init-lenient: false
+      init-fail-on-error: true
+      build-ref: refs/pull/${{ github.event.number }}/merge
+
+  # 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-docs:
+    permissions:
+      contents: read
+    name: Build Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-pr.yml@main
+    with:
+      init-lenient: true
+      init-fail-on-error: false
+      render-file-line: '> * `$<status>` [$<path_tail>](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr/${{ github.event.number }}/$<path_tail>)'
+
+  publish-docs-gh-pages:
+    # use to prevent running on forks
+    if: github.repository == 'repo_owner/repo_name'
+    permissions:
+      contents: write
+    needs: [build-docs]
+    name: Publish Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
+    with:
+      artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
+      action: ${{ (github.event.action == 'closed' || needs.build-docs.outputs.changed != 'true') && 'teardown' || 'publish' }}
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  comment:
+    permissions:
+      pull-requests: write
+    runs-on: ubuntu-latest
+    needs: [publish-docs-gh-pages, build-docs]
+    name: PR comments
+    steps:
+      - name: PR comment
+        uses: ansible-community/github-docs-build/actions/ansible-docs-build-comment@main
+        with:
+          body-includes: '## Docs Build'
+          reactions: heart
+          action: ${{ needs.build-docs.outputs.changed != 'true' && 'remove' || '' }}
+          on-closed-action: remove
+          on-merged-body: |
+            ## Docs Build 📝
+
+            Thank you for contribution!✨
+
+            This PR has been merged and the docs are now incorporated into `main`:
+            ${{ env.GHP_BASE_URL }}/branch/main
+          body: |
+            ## Docs Build 📝
+
+            Thank you for contribution!✨
+
+            The docs for **this PR** have been published here:
+            ${{ env.GHP_BASE_URL }}/pr/${{ github.event.number }}
+
+            You can compare to the docs for the `main` branch here:
+            ${{ env.GHP_BASE_URL }}/branch/main
+
+            The docsite for **this PR** is also available for download as an artifact from this run:
+            ${{ needs.build-docs.outputs.artifact-url }}
+
+            File changes:
+
+            ${{ needs.build-docs.outputs.diff-files-rendered }}
+
+            ${{ needs.build-docs.outputs.diff-rendered }}

samples/push-with-build.yml

@@ -0,0 +1,26 @@
+# A simple workflow that runs a strict build against pushes
+# to main, stable branches, and tags, and also runs once a day.
+# This ensures ongoing healthy, buildable docs.
+name: Collection Docs
+concurrency:
+  group: docs-push-${{ github.sha }}
+  cancel-in-progress: true
+on:
+  push:
+    branches:
+      - main
+      - stable-*
+    tags:
+      - '*'
+  schedule:
+    - cron: '0 13 * * *'
+
+jobs:
+  build-docs:
+    permissions:
+      contents: read
+    name: Build Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@main
+    with:
+      init-lenient: false
+      init-fail-on-error: true

samples/push-with-publish-to-gh-pages.yml

@@ -0,0 +1,35 @@
+name: Collection Docs
+concurrency:
+  group: docs-push-${{ github.sha }}
+  cancel-in-progress: true
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+  schedule:
+    - cron: '0 13 * * *'
+
+jobs:
+  build-docs:
+    permissions:
+      contents: read
+    name: Build Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-push.yml@main
+    with:
+      init-lenient: false
+      init-fail-on-error: true
+
+  publish-docs-gh-pages:
+    # use to prevent running on forks
+    if: github.repository == 'repo_owner/repo_name'
+    permissions:
+      contents: write
+    needs: [build-docs]
+    name: Publish Ansible Docs
+    uses: ansible-community/github-docs-build/.github/workflows/_shared-docs-build-publish-gh-pages.yml@main
+    with:
+      artifact-name: ${{ needs.build-docs.outputs.artifact-name }}
+    secrets:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}