For about a year or so now we’ve been looking at how we can open up building and deploying Ansible package docs to the community. It has been a journey with a few twists and turns but, until recently, we’ve been hampered by the fact that the Sphinx build for the package docs needs a pretty beefy host. Red Hat has provided a Jenkins job and some infrastructure for building and deploying the package docs but that is restricted to employees.
So what has changed?
GitHub have boosted the runners for actions, that’s what! Here is the announcement: https://github.blog/2024-01-17-github-hosted-runners-double-the-power-for-open-source/
This means we can use GitHub actions to build package docs. Take a look at a run on my fork: (Don’t pay too much attention to the actual workflow. It’s kind of cringe and I just threw it together.) Ansible package docs build · oraNod/ansible-documentation@4572c75 · GitHub
Where does this take us?
Now that we can build package docs on GitHub-hosted runners, we can create a workflow like this:
- Build the package docs.
- Create an archive with the resulting HTML.
- Download the archive and create a release.
From there it would be possible to deploy the package docs on Read The Docs using the release build. Here is an example of how that would look: Ansible Documentation — Ansible Documentation
And here is the RTD config: ansible-documentation/.readthedocs.yaml at devel · oraNod/ansible-documentation · GitHub
There are some kinks to work out and some decisions to make but at least we can now see a fairly straightforward path for making the package docs build available to the community.
What is there to discuss?
I’m pretty sure everyone is cool with the idea of building package docs with an action. I’m less confident everyone is cool with deploying and hosting package docs on Read The Docs. It is a more accessible hosting option than the current “restricted to Red Hat employees” option we have now.
If community members want to handle the deploy side of things they will need to give Read The Docs some permissions: How to automatically configure a Git repository — Read the Docs user documentation
Is there a more suitable alternative than Read The Docs out there?
Should we just leave the current deploy side of things as-is in the interest of maintaining SEO authority?
If we migrate the hosting to Read The Docs this could potentially break a bunch of existing redirects and require new redirects. We should be cautious about making too many changes to content under docs.ansible.com/ansible to avoid mass confusion and making it super hard for users to find help in the docs.
Is it wiser to err on the side of caution and update that Jenkins job I mentioned before to pick up the release artifact and deploy it to the web server? Is it enough for the community to build the package docs and leave the deploy side to Red Hat?
The big downside for the community there might be that we never bring the package docs and the rest of the ecosystem together - we’ll be in the same boat we’re in now with docs.ansible.com and ansible.readthedocs.io. It would be pretty sweet to bring all the documentation under one domain.
By the way, this discussion relates to Can we group all ecosystem project docs under the docs.ansible.com domain? - #3 by samccann and probably a couple other topics with the documentation tag.