[DOCS] Module Examples vs FQCN

[gundalow]

SUMMARY

Need to document this:

1. Modules that were in ansible/ansible before the mass migration can continue to be used by the short form thanks to routing.yml
2. New modules (ie ones that have only existed in a Collection) will not work in the short form unless Playbook authors add the collection: form
3. EXAMPLES for new modules MUST have FQCN. This means Playbook authors can copy-paste examples without having to set collections:
4. FQCN and namespaces are a feature, we want to make more people aware of them. Though we MUST NOT break 2.9 Playbooks
5. For smaller collections like Crypto I think it's OK to bulk update all examples to use FQCN
6. EXCEPTION: I'm not sure if it makes sense to bulk update EXISTING modules docs in community,general. I expect we will continue to move content out of community.general into smaller Collections (like we've just done with Network, rabbitmq, etc). Adding in FQCN may confuse that matter.
7. No more entries (modules or plugins) will be added to routing.yml. The entries was frozen in time when pre-ansible-base was tagged. Hence 3.

Places to update

• Module & plugin docs
• Examples repos
• Training materials

[briantist]

One thing to mention is that updating the examples to use FQCN will sometimes cause line-length lint errors where there were none before.

For example I had to cut some stuff out of some of the examples here to make them fit and pass tests after updating the plugin name: ansible-collections/community.general@5186d04

It might be worth considering whether line length should be extended for examples (if that's even possible), or how to deal with the inevitable test failures after a mass update.

This probably affects lookup plugins more since they tend to be written as one line. Maybe some guidance on a preferred multi-line format for examples might help?

Like this:

- name: Vault that requires authentication via LDAP
  debug:
    msg: "{{ lookup('community.general.hashi_vault', 'secret=secret/hello:value auth_method=ldap mount_point=ldap username=myuser password=mypas url=http://myvault:8200')}}"

becomes:

- name: Vault that requires authentication via LDAP
  debug:
    msg: "{{ 
      lookup(
        'community.general.hashi_vault', 
        'secret=secret/hello:value auth_method=ldap mount_point=ldap username=myuser password=mypas url=http://myvault:8200'
      )
    }}"

(^ ugly and not necessarily suggesting that format)

[felixfontein]

Considering that on smaller-width devices (or windows) you need to horizontally scroll to read the full example, I prefer the second one (which you call ugly) since I can understand it without having to scroll :) Also, the structure of the expression is easier to understand (in the docs there's Jinja2 highlighting, but not here in GitHub).

So far I was mainly thinking of module docs though, and there line length isn't really a problem. But for anything which ends up in Jinja2 expressions it can indeed be! Thanks for pointing that out.

[briantist]

Yeah I use the second one often myself as I prefer it too; ugly may have been a bit too far. Though it might be a little confusing for people new to Ansible. So I do think there should be a short list of recommended formats for use in docs.

Showing multiple format is helpful too, but keeping it down to a few might be better.

Didn't realize about the syntax highlighting within the docs that's a good point that will help a lot with readability.

[geerlingguy]

Regarding the 'ugly' second example—I know that one of the most annoying things new users run into is the many different ways line breaks and indentation are handled in Ansible playbooks/YAML. From tab/space indentation issues to whether to use the folded scalar, block chomping indicator, etc., this does not make for a fun first-time user experience. (And that's before we throw in the fact that spaces can have weird affects on bare variables, strings, and jinja2 strings and strings-in-variables...)

That's why I'm still electing to not use the FQCN anywhere in examples in my introductory materials, because it causes the examples to be extremely verbose/obtuse/indecipherable, whereas adding:

collections:
  - community.general

Prevents any such verbosity in the rest of the playbook/resources (assuming, of course, we someday get ansible/ansible#68198 reopened and fixed...).

I'm still waiting for an argument in favor of forcing FQCNs everywhere (for tasks, that is). Even as someone who fully understands the why and background, I will not be using FQCNs in tasks until the ability to not do so is pried from my cold, dead hands.

[geerlingguy]

Another potential option (though this may have already been dismissed elsewhere?): What if every example were in the context of a playbook?

Right now examples are kind of tossed into a code block, and there's no playbook context.

For the Kubernetes collection, there's an example playbook with modules being used inside it: https://github.com/ansible-collections/kubernetes#using-modules-from-the-kubernetes-collection-in-your-playbooks

So instead of examples for module docs being like:

- namespace.collection.module:
    option: value
    option2: "{{ lookup('community.general.hashi_vault', 'secret=secret/hello:value auth_method=ldap mount_point=ldap username=myuser password=mypas url=http://myvault:8200')}}"

The examples could be like:

- hosts: all

  collections:
    - namespace.collection

  tasks:
    - module:
        option: value
        option2: "{{ lookup('hashi_vault', 'secret=secret/hello:value auth_method=ldap mount_point=ldap username=myuser password=mypas url=http://myvault:8200')}}"

[geerlingguy]

This would also have the benefit that documentation remains the same (for individual tasks) between ACD and all Ansible versions prior (instead of people wondering why community.general.hashi_vault is throwing errors in 2.8).

[briantist]

I love the idea in theory but according to the Using collections docs you always need FQCN for everything except modules (emphasis mine):

This keyword [the collections: keyword] creates a ‘search path’ for non namespaced plugin references. It does not import roles or anything else. Notice that you still need the FQCN for non-action or module plugins.

I presume there's some reason for that decision; I wish collections: worked with all references.

[gundalow]

WIP script to update module docs from short form to FQCN https://github.com/ansible-network/collection_prep

[gundalow]

Sivel's version of a rewrite script https://gist.github.com/sivel/1f850b7f577b9dc9466293034c82b19d

[gundalow]

Done and documented in https://github.com/ansible-collections/overview/blob/main/collection_requirements.rst#documentation