Integrate ansible-creator and devtools into the developing collections guide

[xszabo3]

This branch adds a section mentioning ansible-creator as a way to generate collection structure. Mentioned in #1294

[ansible-documentation-bot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at #docs:ansible.im and on libera IRC at #ansible-docs if you ever want to join us and chat about the docs! We meet there on Tuesdays (see the Ansible calendar) and welcome additions to our weekly agenda items - scroll down to find the upcoming agenda and add a comment to put something new on that agenda.

[oraNod]

Thanks for the docs update @xszabo3 I've made a few suggestions for you. Feel free to rewrite and work with them however you see fit.

[oraNod]

Also @xszabo3 I just realized you opened this PR as a draft. If you're not ready for review comments yet, please just ignore what I put in there.

[xszabo3]

Thanks for the feedback @oraNod . I will make the changes when I have time in the following days, I also asked a few questions in the matrix channel after making this draft.

[xszabo3]

@oraNod I haven't received an answer on matrix, so I will repeat the questions here:

1:
Which collection creating method should be recommended? (with ansible-creator or the already present method) I could add a note, or change the order so the recommended section will be the first.
1.5 - Will the template_repository stay the recommended in https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_path.html#put-your-content-in-a-collection ?

2:
Found a possible typo in the style guide. At https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html#internal-navigation in the note the first ` is missing from the external link.

[oraNod]

@oraNod I haven't received an answer on matrix, so I will repeat the questions here:

1: Which collection creating method should be recommended? (with ansible-creator or the already present method) I could add a note, or change the order so the recommended section will be the first. 1.5 - Will the template_repository stay the recommended in https://docs.ansible.com/ansible/devel/dev_guide/developing_collections_path.html#put-your-content-in-a-collection ?

2: Found a possible typo in the style guide. At https://docs.ansible.com/ansible/latest/dev_guide/style_guide/index.html#internal-navigation in the note the first ` is missing from the external link.

hey @xszabo3 I might have missed those questions in matrix. as a general rule of thumb it's better to ask questions related to a PR or issue directly in the thread. it's especially helpful to have the full context in one place for historical purposes too.

1. Maybe let's keep the ansible-creator method more like a hint or tip but not the recommended primary method. It shouldn't come before what is already there.
   1.5 Yes, let's not change that. It is actively maintained by the community and should be recommended for consistency.
2. Well spotted. Yes, that looks like either a typo or possibly a character that needs to be escaped. Feel like sending a PR to fix it?

[oraNod]

@Andersson007 Hi, I think we should get your perspective on this because we don't want to deviate too much from the collection template repository in community. Could you please take a look and share any opinion on using the ansible-creator tool? Thanks.

[xszabo3]

2. Well spotted. Yes, that looks like either a typo or possibly a character that needs to be escaped. Feel like sending a PR to fix it?

Thanks for the response @oraNod , I just opened a PR for the typo.

[xszabo3]

After changing the anchors, I think the first point deserves a rewrite, to include ansible-creator

I have a few suggestions:
1:

Create a new collection, optionally using a custom collection template, with the ansible-galaxy collection init command, or use the ansible-creator tool.

2:

Create a new collection with the ansible-galaxy collection init command, optionally using a custom collection template or using ansible-creator.

3:

Create a new collection, optionally using a custom collection template, either with the ansible-galaxy collection init command or using ansible-creator.

4: Leave it as it is

Which one would be the most ideal, or do you have other ideas @oraNod @samccann ?

[oraNod]

LGTM. Thanks for the contribution @xszabo3

[patchback]

Backport to stable-2.15: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply fd3495a on top of patchback/backports/stable-2.15/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302

Backporting merged PR #1302 into devel

1. Ensure you have a local repo clone of your fork. Unless you cloned it
   from the upstream, this would be your origin remote.
2. Make sure you have an upstream repo added as a remote too. In these
   instructions you'll refer to it by the name upstream. If you don't
   have it, here's how you can add it:

   $ git remote add upstream https://github.com/ansible/ansible-documentation.git

3. Ensure you have the latest copy of upstream and prepare a branch
   that will hold the backported code:

   $ git fetch upstream
   $ git checkout -b patchback/backports/stable-2.15/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302 upstream/stable-2.15

4. Now, cherry-pick PR Integrate ansible-creator and devtools into the developing collections guide #1302 contents into that branch:

   $ git cherry-pick -x fd3495af6394922cfc81344c42133a0fb62f98c7

   If it'll yell at you with something like fatal: Commit fd3495af6394922cfc81344c42133a0fb62f98c7 is a merge but no -m option was given., add -m 1 as follows instead:

   $ git cherry-pick -m1 -x fd3495af6394922cfc81344c42133a0fb62f98c7

5. At this point, you'll probably encounter some merge conflicts. You must
   resolve them in to preserve the patch from PR Integrate ansible-creator and devtools into the developing collections guide #1302 as close to the
   original as possible.
6. Push this branch to your fork on GitHub:

   $ git push origin patchback/backports/stable-2.15/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302

7. Create a PR, ensure that the CI is green. If it's not — update it so that
   the tests and any other checks pass. This is it!
   Now relax and wait for the maintainers to process your pull request
   when they have some cycles to do reviews. Don't worry — they'll tell you if
   any improvements are necessary when the time comes!

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

[samccann]

Thanks @xszabo3 for the Ansible docs fix!

[patchback]

Backport to stable-2.14: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply fd3495a on top of patchback/backports/stable-2.14/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302

Backporting merged PR #1302 into devel

1. Ensure you have a local repo clone of your fork. Unless you cloned it
   from the upstream, this would be your origin remote.
2. Make sure you have an upstream repo added as a remote too. In these
   instructions you'll refer to it by the name upstream. If you don't
   have it, here's how you can add it:

   $ git remote add upstream https://github.com/ansible/ansible-documentation.git

3. Ensure you have the latest copy of upstream and prepare a branch
   that will hold the backported code:

   $ git fetch upstream
   $ git checkout -b patchback/backports/stable-2.14/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302 upstream/stable-2.14

4. Now, cherry-pick PR Integrate ansible-creator and devtools into the developing collections guide #1302 contents into that branch:

   $ git cherry-pick -x fd3495af6394922cfc81344c42133a0fb62f98c7

   If it'll yell at you with something like fatal: Commit fd3495af6394922cfc81344c42133a0fb62f98c7 is a merge but no -m option was given., add -m 1 as follows instead:

   $ git cherry-pick -m1 -x fd3495af6394922cfc81344c42133a0fb62f98c7

5. At this point, you'll probably encounter some merge conflicts. You must
   resolve them in to preserve the patch from PR Integrate ansible-creator and devtools into the developing collections guide #1302 as close to the
   original as possible.
6. Push this branch to your fork on GitHub:

   $ git push origin patchback/backports/stable-2.14/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302

7. Create a PR, ensure that the CI is green. If it's not — update it so that
   the tests and any other checks pass. This is it!
   Now relax and wait for the maintainers to process your pull request
   when they have some cycles to do reviews. Don't worry — they'll tell you if
   any improvements are necessary when the time comes!

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

[patchback]

Backport to stable-2.16: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply fd3495a on top of patchback/backports/stable-2.16/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302

Backporting merged PR #1302 into devel

1. Ensure you have a local repo clone of your fork. Unless you cloned it
   from the upstream, this would be your origin remote.
2. Make sure you have an upstream repo added as a remote too. In these
   instructions you'll refer to it by the name upstream. If you don't
   have it, here's how you can add it:

   $ git remote add upstream https://github.com/ansible/ansible-documentation.git

3. Ensure you have the latest copy of upstream and prepare a branch
   that will hold the backported code:

   $ git fetch upstream
   $ git checkout -b patchback/backports/stable-2.16/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302 upstream/stable-2.16

4. Now, cherry-pick PR Integrate ansible-creator and devtools into the developing collections guide #1302 contents into that branch:

   $ git cherry-pick -x fd3495af6394922cfc81344c42133a0fb62f98c7

   If it'll yell at you with something like fatal: Commit fd3495af6394922cfc81344c42133a0fb62f98c7 is a merge but no -m option was given., add -m 1 as follows instead:

   $ git cherry-pick -m1 -x fd3495af6394922cfc81344c42133a0fb62f98c7

5. At this point, you'll probably encounter some merge conflicts. You must
   resolve them in to preserve the patch from PR Integrate ansible-creator and devtools into the developing collections guide #1302 as close to the
   original as possible.
6. Push this branch to your fork on GitHub:

   $ git push origin patchback/backports/stable-2.16/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302

7. Create a PR, ensure that the CI is green. If it's not — update it so that
   the tests and any other checks pass. This is it!
   Now relax and wait for the maintainers to process your pull request
   when they have some cycles to do reviews. Don't worry — they'll tell you if
   any improvements are necessary when the time comes!

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

[patchback]

Backport to stable-2.17: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-2.17/fd3495af6394922cfc81344c42133a0fb62f98c7/pr-1302

Backported as #1399

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

[xszabo3]

Thanks @xszabo3 for the Ansible docs fix!

Thank you all for your patience.
I opened PRs for backports (the conflict was with the custom template, I leave it up to you if it needs a backport or not).