workflow shared-docs-build-push: add `artifact-upload` and `build-ref` options

[briantist]

This modifies the push build workflow so that you can:

• specify whether or not to upload the build as an artifact (defaults to true, no change in behavior)
• specify which ref to checkout (defaults to none which defaults to actions/checkout default, no change in behavior)

These changes make the workflow useful for running a "validation" job, by changing the lenient and fail-on-error options. This was already possible for push workflows, but the artifact uploaded was redundant and couldn't be turned off.

For PRs, this was not possible with pull_request_target events (which we usually use) because we had no way to tell the workflow to use the PR ref (the default would have been the PR target, like main). Now we can tell the workflow to use the merge commit or whatever on PRs.

Examples

(Currently shown referencing this PR's version of the workflow)

PR

name: Collection Docs
concurrency:
  group: docs-pr-${{ github.head_ref }}
  cancel-in-progress: true
on:
  pull_request_target:
    types: [opened, synchronize, reopened, closed]

jobs:
  validate-docs:
    permissions:
      contents: read
    name: Validate Ansible Docs
    if: github.event.action != 'closed'
    uses: briantist/github-docs-build/.github/workflows/_shared-docs-build-push.yml@workflows/build-push/choose-ref
    with:
      artifact-upload: false
      init-lenient: false
      init-fail-on-error: true
      build-ref: refs/pull/${{ github.event.number }}/merge

Push

name: Collection Docs
concurrency:
  group: docs-push-${{ github.head_ref }}
  cancel-in-progress: true
on:
  push:
    branches:
      - main
      - stable-*
    tags:
      - '*'

jobs:
  validate-docs:
    permissions:
      contents: read
    name: Validate Ansible Docs
    uses: briantist/github-docs-build/.github/workflows/_shared-docs-build-push.yml@workflows/build-push/choose-ref
    with:
      artifact-upload: false
      init-lenient: false
      init-fail-on-error: true

[briantist]

I have tested these changed on my fork of community.docker, though I probably won't keep those commits around. The defaults have the same behavior as the previous iteration as well, so will merge now.