first shot at building docs on PRs with shared workflow

[briantist]

SUMMARY

I've spent my holiday reimplementing the docs build process so it can be shared with other collections in a way that's straightforward.

What I'm proposing here is a first step at re-using that stuff to have a docs build in this collection, on PRs.

It's quite short, because it's using the basics of the shared workflows/actions I created, with mostly default parameters.

There's no publishing step here, because that will need you to sign up with some other service and put any relevant secrets you need into GitHub.

However, you can see what that looks like in the workflow I'm using where I publish to Surge. I made that as a shared workflow, so that if anyone else wants to use it, it's super straightforward to do so.

Maybe we'll see some shared workflows or other publishing destinations like RTD.

---

So here's a few things about this PR:

• The workflow uses the pull_request_target trigger, so it will not be run in this PR. Unfortunately this means it can't be tested in this PR either; it will have to be landed to main first before we can test against changes to it. After that, the process of testing changes is a little complicated, to see more details about that, read docs build - process notes and TODOs community.hashi_vault#138 (perhaps skip to Put workflow changes on a direct branch, open other PRs against the branch).
• The result of merging this will be that PRs will have their changes run through this process and have docs built for the base and head of the PR, and if the content differs, a comment will be posted linking to the build artifacts for the run so that the one can download the archive with the rendered HTML.
• Once merged to main, it can be tested immediately by putting up a test PR (from a fork works too).
• If there are problems with the workflow that can't be addressed quickly, and you want to avoid a "failing" build on PRs, the workflow can be disabled directly from the Actions page, without needing to move/delete the file or make any new commits.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

ansible collection docs

ADDITIONAL INFORMATION

N/A

[felixfontein]

Right now this workflow depends on actions and workflows in https://github.com/ansible-collections/community.hashi_vault/; I think long-term we should move that to another repository, but for now let's keep this (as some kind of experiment) :)