add steps to deploy doc build assets

[oraNod]

This PR updates the workflow to build package docs with an input to push generated HTML and other assets to a remote repository. After the build is pushed to the remote, a Python script copies the assets to the ReadTheDocs html directory. The push also triggers the ReadTheDocs automatic build.

Note that this PR is in draft state because it contains my personal GitHub config details and a reference to a temporary token. Before this gets merged, we'll need to figure out the best way to replace those bits. Additionally, we'll need to figure out how to limit access to the workflow so that only members of the community-docs-maintainers group can run it.

For an example of how this works, see this job in my fork: https://github.com/oraNod/ansible-documentation/actions/runs/8837905175/job/24267821667

The push goes to this repository that holds the Python script: https://github.com/oraNod/ansible-docs-deploy

And here is the example ReadTheDocs project: https://readthedocs.org/projects/oranod-ansible-docs-deploy/

You can find the published docs here: https://oranod-ansible-docs-deploy.readthedocs.io/en/latest/

[oraNod]

@webknjaz Would you mind please giving this a look and providing some first impressions? As I mentioned in the description we'll need to replace the token and git config. I'm still unsure of whether a GitHub App is the best way to go here. The push doesn't need to go via the API so perhaps we could use something like a service account. Thanks!

[webknjaz]

I'm still unsure of whether a GitHub App is the best way to go here. The push doesn't need to go via the API so perhaps we could use something like a service account.

This is an additional user to maintain everywhere. A GitHub App is more controlled and granular. It is also possible to make a deployment key (SSH) — it's public part is added to the target repo and the private one goes to this repo's secrets. This is how pushing from https://github.com/ansible-community/antsibull/blob/62c44db/.github/workflows/build-dumb-pypi.yml#L196 to https://github.com/ansible-community/nightly-builds (https://ansible-community.github.io/nightly-builds/) is set up.

[webknjaz]

Use a separate GitHub Environment for the job doing publishing so it has access to secrets but other jobs don't. Separate building out into a standalone job and pass the data between them through artifacts.

[webknjaz]

Additionally, we'll need to figure out how to limit access to the workflow so that only members of the community-docs-maintainers group can run it.

If you separate out a publishing job like I described, you can use the environment attached to it to control who can approve that job run. As for the build part, it's normally useful to run it unconditionally, including on PRs, if it's not too expensive.

[oraNod]

@gotmax23 @felixfontein I've tested this workflow in my fork and a throwaway destination repo. I've used a different key for the deploy but all the other repo settings are mirrored, including branch protection rules (except for the workflow approval in the environment).

Test One: Deploy to Read the Docs / Production

• Workflow run: https://github.com/oraNod/ansible-documentation/actions/runs/9462560523/
• Commit: oraNod/ansible-docs-deploy@9120f12
• Published docs: https://oranod-ansible-docs-deploy.readthedocs.io/en/latest/

Test Two: Deploy to GH Pages / Test

• Workflow run: https://github.com/oraNod/ansible-documentation/actions/runs/9463222300/
• Commit: oraNod/ansible-docs-deploy@4a89b50
• Norobot.txt file: https://github.com/oraNod/ansible-docs-deploy/blob/gh-pages/docs/norobots.txt
• Published docs: https://oranod.github.io/ansible-docs-deploy/

It looks like the styles aren't being applied on gh-pages though. Hmm...

Edit: Looks like we need to deploy the test site to gh-pages with a simple workflow rather than the "classic" experience of using a branch. Though that's something to fix in the destination repo, not this workflow.

[samccann]

Can't speak to the actual workflow yaml contents, but looks logical to me and the test outputs look good.

I don't see the formatting problem @oraNod that you saw in the gh pages. Doesn't slow down this PR merge but would love to know what you saw that I can't seem to find :-)

[oraNod]

@samccann hey, thanks for the review! the problem was that none of the styles were applied so it was just unformatted html. this seemed to be caused by the GitHub pages config, which I've fixed in a separate pr.

[oraNod]

sorry, I'm probably not being entirely clear. I fixed the problem in my test repo and opened the PR for the actual destination repo. in any case it's not a problem with the changes here.

[samccann]

Ah okay... I saw that open PR but didn't put 2+2 together to realize the test links above were using it. Do you want me to merge now so you don't have to self-merge?

[oraNod]

Ah okay... I saw that open PR but didn't put 2+2 together to realize the test links above were using it. Do you want me to merge now so you don't have to self-merge?

@samccann If you feel like this is good to go and we're fine to merge, I'd certainly appreciate not having to self-merge. I never like doing that honestly. I don't want to be too pushy about it though. If folks like @felixfontein or @webknjaz want another couple days to review or whatever, I guess we can wait.

[samccann]

Mostly so that it's ready on Monday am (your time Don) for whatever your next steps are. But PRs welcome for sure if something is wrong here( or even comments in this PR). Thanks everyone!

[oraNod]

thanks @samccann and everyone! 🚀