Better document local collections for playbooks

[felixfontein]

Right now this is mentioned at the bottom of docs/docsite/rst/shared_snippets/installing_collections.txt. This is impossible to link to, and hard to find in general.

Having this documented in a better place would be great!

Ref: https://forum.ansible.com/t/building-html-documentation-for-standalone-local-module-where-to-find-makefile/3915/4

[samccann]

So looking at this page - https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html - it doesn't specifically mention local collections. So we could add a new section/header to talk about these local collections adjacent to the playbook dir.

What do you think about adding a short new section before this one - https://docs.ansible.com/ansible/latest/collections_guide/collections_installing.html#installing-a-collection-from-source-files?

[spike77453]

Food for though: this page https://docs.ansible.com/ansible/latest/tips_tricks/sample_setup.html (which used to be called "Best Practices/Content Organization": https://docs.ansible.com/ansible/2.9/user_guide/playbooks_best_practices.html#content-organization) should probably also mention that putting local collections adjacent to playbooks is possible.

[oraNod]

Estimated effort: M (MUNI tech writers)

[Devids10]

Hello! I would like to work with this issue. I am from the MUNI tech writing course. (This having 2S and 1 M issue to complete)

[samccann]

So looking at this more deeply, there are two problems to fix:

1. I thought I was smart way back when in creating 'reusable snippets'. Ends up I was not so smart, and it just causes problems. It's also no longer 'reused' in any other location but this installing section.
2. Once 1 is fixed, we then have an anchor we can use to link to this new heading.

This is subject to @oraNod 's thoughts/modifications, but here's how I think we can fix this:

1. Open a PR that removes that reusable snippet file and just copies the content to the one location where it is currently used:

• https://github.com/ansible/ansible-documentation/blob/devel/docs/docsite/rst/collections_guide/collections_installing.rst?plain=1#L19
• In this same PR, change that local collections part to have a heading and anchor.

Once that PR is merged:
2 - Open a PR to sprinkle links to that section as described in prior comments here.

[oraNod]

@samccann Hi, I'm a bit confused with your comment. Did you mean to reference that PR that adds sanity tests or something else?

I also think it's a good plan to remove the reusable snippet and create a "proper" section with a heading and anchor that we can reference elsewhere. I'm not sure that needs to be in two separate PRs but it wouldn't hurt.

[oraNod]

@Devids10 Here are some ideas for things you could include in that new section to expand it a little. Feel free to rewrite in your own voice and make whatever tweaks:

Installing collections adjacent to playbooks

You can install collections locally next to playbooks in your project instead of in a global location on your system or AWX. This approach has some benefits, such as:

• Ensuring all users of the project use the same version of the collection for consistency.
• Using self-contained projects makes it easy to move across different environments. Increased portability also reduces overhead when setting up new environments. This could be a real benefit when deploying Ansible playbooks in cloud environments.
• Managing collections locally lets you version them along with your playbooks.
• Installing collections locally isolates them from global installations in environments that have multiple projects.

There might be some other things that I'm not thinking about here. @felixfontein might have some ideas (or be a good person to call me out on any nonsense).

HTH!

[Devids10]

@oraNod Thank you so much for the ideas. I'll sure look through it and rewrite it if necessary.
Although what now I am thinking about is the original issue, aka the 1st link. That is also going to transfer under this section, or will it be removed totally?

[oraNod]

@oraNod Thank you so much for the ideas. I'll sure look through it and rewrite it if necessary. Although what now I am thinking about is the original issue, aka the 1st link. That is also going to transfer under this section, or will it be removed totally?

@Devids10 Yes, I think we can remove those lines here https://github.com/ansible/ansible-documentation/blob/devel/docs/docsite/rst/shared_snippets/installing_collections.txt#L59-L68 and put them in a new section.

In fact you could probably move the entire contents of the shared snippets file into the RST file where it is referenced, instead of just those specific lines.

[samccann]

@samccann Hi, I'm a bit confused with your comment. Did you mean to reference that PR that adds sanity tests or something else?

Ah github got too clever for me. I type # 1 (without the space) to mean my first item in the comment, but github treated it as a link to an issue. I edited my comment to remove that confusion.

[Devids10]

@oraNod I have created a draft MR, since I did some changes and created the new section, although currently I am unsure what is this "shared snippets file" and what "RST file" you're talking about. Perhaps I already done what you asked me to do, but some clarification would be great.

And as of now some checks are failing as well, for which I am quite unsure why is it failing.

EDIT: This time I was looking at the build from readthedocs, and the new section I added is not visible. Why is that?