Documentation build process

[briantist]

Summary

As discussed in: https://meetbot.fedoraproject.org/ansible-docs/2022-01-04/documentation_working_group_aka_dawgs.2022-01-04-15.59.html

See also:

• docs build - process notes and TODOs ansible-collections/community.hashi_vault#138

---

The docs build process I put together on community.hashi_vault has been reimplemented as a set of GitHub Actions and Reusable workflows, so that it can be consumed by other collections fairly easily.

The actions currently reside in the community.hashi_vault repo:

• actions: https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/actions/docs
• workflows (_shared*): https://github.com/ansible-collections/community.hashi_vault/tree/main/.github/workflows

However, they should be moved to their own repository or repositories, so they can be managed as the separate project they are.

First question is: single repo, or multiple repos.

Why would we want multiple?

GitHub actions and workflows are referenced by git ref as their "versioning" system. If all of these components live in a single repo, it is not possible to "release" (typically done with tags) independent versions of the components.

If we were publishing several unrelated actions and workflows, then it would make sense to split them up, but because these are related, and because the shared workflows will reference some of the actions, I think it's ok, and maybe beneficial, to put them in a single repo. This may also simplify testing.

Additionally, consumers do not need to use the same git ref for each action/workflow just because they live in the same repo, it is possible to use ActionA@ref1 and ActionB@ref2, to get "independent" versions of each, it's just less clear that ActionC@ref1 and ActionC@ref2 may be exactly the same because they had no changes between what may be major versions. But I guess that's not much different from content in collections for example ;)

Additional Information

No response

[felixfontein]

I'm for a single repository for all docs-related actions and workflows. These are all related, and also interact with each other, so there's no reason to spread them over multiple repositories (which makes development only more complicated).

[briantist]

I agree; and from the meeting it sounds like everyone else agrees too. The sooner we can get a repo going the better imo.

[briantist]

Having joined the steering committee, it looks like I have rights to create a new repository within ansible-community. Any objections with me going forward with it?

Any ideas on naming?

[gundalow]

I'm for a single repository for all docs-related actions and workflows. These are all related, and also interact with each other, so there's no reason to spread them over multiple repositories (which makes development only more complicated).

+1 to a new single repo

Having joined the steering committee, it looks like I have rights to create a new repository within ansible-community. Any objections with me going forward with it?

I'm happy for you to create a repo under ansible-community for this.

Any ideas on naming?

docs-build?

[felixfontein]

How about github-docs-build, since these are GitHub-specific things?

[briantist]

🎉https://github.com/ansible-community/github-docs-build

I've still got quite a bit of documentation to write, and I'm using the repo's Wiki to do so.

I've added several known issues and areas for improvement.

I've also enabled the Discussions feature as that might be a better place than Issues for improvement requests and troubleshooting Q&A.