diff --git a/samples/README.md b/samples/README.md new file mode 100644 index 0000000..e34c254 --- /dev/null +++ b/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. diff --git a/samples/pr-build-and-comment.yml b/samples/pr-build-and-comment.yml new file mode 100644 index 0000000..f8ee21b --- /dev/null +++ b/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 }} diff --git a/samples/pr-with-publish-to-gh-pages.yml b/samples/pr-with-publish-to-gh-pages.yml new file mode 100644 index 0000000..7f872ec --- /dev/null +++ b/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: '> * `$` [$](https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr/${{ github.event.number }}/$)' + + 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 }} diff --git a/samples/push-with-build.yml b/samples/push-with-build.yml new file mode 100644 index 0000000..e92c948 --- /dev/null +++ b/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 diff --git a/samples/push-with-publish-to-gh-pages.yml b/samples/push-with-publish-to-gh-pages.yml new file mode 100644 index 0000000..85a260c --- /dev/null +++ b/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 }}