add steps to deploy doc build assets to prod

[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]

@webknjaz I registered a GH app and installed it in both my forks to test things out. It works quite nicely, I think. This might be preferable to the deploy key that you mentioned in your earlier comment.

The GH app approach would probably be easier to use and familiar to other maintainers like @samccann who recently made some changes to the documentation bot app.

I tested the deployment workflow with my GitHub app using my fork. That pushed a test commit to my destination repo and updated my RTD deployment.

The next steps to take this PR out of draft will be to create the destination repo in ansible-community. I guess then we'll need to transfer ownership of the GH app to the Ansible org and then specify the two repos that the app needs to access, which will be ansible/ansible-documentation and the destination repo. After that we'll just need to create the environment with the two secrets in ansible/ansible-documentation. Sound like a plan?

[oraNod]

@felixfontein @gotmax23 @samccann Hi, this PR has been sitting as a draft while I've been hacking on it with Sviat but I feel like it's mostly ready and wanted to get your thoughts. I'll pull it out of draft mode once I create the destination repository and fill in those details here.

As a brief recap (because I know details are probably floating all over the place), the idea is to do a package docs build that creates a tarball. Then we'll have a second job that unpacks the tarball and pushes the HTML and other resources to a path in destination repo such as this one: https://github.com/oraNod/ansible-docs-deploy

We can then copy all the HTML and other assets to a readthedocs project, ansible.readthedocs.io/projects/ansible.

[gotmax23]

Why not put this in the ansible organization where the actual docs repo already lives?

[oraNod]

There was some discussion about this in one of the DaWGs meetings and the consensus seemed to be putting it in ansible-community would avoid any other access issues with the SC (although I know that is more about the source). I'm also aware that there is an ongoing conversation about splitting the source into "core docs" and "community docs", in which case "community docs" could move into ansible-community. Maybe @samccann can pipe in here with some more detail.

In essence the motivation to put the destination repo in ansible-community is to avoid having the entire publishing workflow be limited in terms of access to the community. I've wondered the same thing about putting the repo in ansible honestly so I'm glad you asked. We can still change where it goes. Do you have any preference for one or the other @gotmax23 ?

[samccann]

My nickel - keep it in ansible-community. This is the build for the package docs, not core docs (regardless of what direction a possible split might go). The community can have full rights in ansible-community that we can't provide in the Ansible org.

We can follow up with core folks so they know what we are doing here for sure, in case there is some gotcha I'm not thinking about, but this is just the HTML files etc.