blocks, local_action, ... discoverability issue

[agowa]

trafficstars

Summary

Hi, currently it is a bit hard to find the documentation for e.g. "block" and "local_action". Strictly speaking they're not "builtin modules" but statements. However it is fair to assume that users would look first into this index page for ansible.builtin when looking for them. esp. because the search in the wiki is kinda bad at surfacing information for any of the keywords, also their options aren't that well documented currently either.

Therefore I'd like to suggest two things.

1. ~If not already supported allow block to also be written as ansible.builtin.block, local_action as ansible.builtin.local_action, and so on. (this is optional, but they're designed to look like a modules within a playbook and are builtin. Therefore at least for me this would make sense).~ Declined in https://github.com/ansible/ansible/issues/84312
2. Add documentation using the module docs-template and add them to the index page of ansible.builtin. Either within their own section or as "just another module". So that all of their options are documented in our standard format at a place with better SEO.

I regularly hit this discoverability issue when looking for either some of the advanced parameters/syntax or when trying to help someone new to ansible solve a problem that demands them.

Also, about local_action in particular, for its verbose syntax it is currently not documented how to call a module that accepts a free_form argument e.g. ansible.builtin.shell module. New people (if they find the docs of it at all) often write it either:

- name: Example A
  ansible.builtin.local_action:
    module: ansible.builtin.shell echo foobar
- name: Example B
  ansible.builtin.local_action:
    module: ansible.builtin.shell
    free_form: echo foobar

What do you think? Yey or Ney?

Additional Information

Relevant code:

• https://github.com/ansible/ansible/blob/devel/lib/ansible/playbook/task.py#L241

Relevant documentation:

• https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html
• https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_blocks.html
• https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_delegation.html

[ansible-documentation-bot[bot]]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.

[samccann]

Hey @agowa - thanks for opening the issue!

So we just changed the search engine for the docs last night. Today, the block search result seems good. Can you take another look for that one?

local_action is still problematic, but I think we can fix that by giving it a header. I think experimenting with https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html to get each of those keywords to show up in search results would be the improvement we want to make here, correct?

I'm disinclined to add to the collection index as it's mixing things up to solve a search problem. Instead, let's fix the search problem itself.

[agowa]

The block one is almost perfect now. The search shows the keywords page as well as the dedicated Block pages (The 2nd result is a forwarding to the 3rd, maybe we can hide it?)

Only thing we should still change is having this section have a link to this page: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_blocks.html#blocks

for the "local_action" one this page should (somehow) become the top result: https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_delegation.html

I'm disinclined to add to the collection index as it's mixing things up to solve a search problem. Instead, let's fix the search problem itself.

Well the reasoning behind my suggestion is simple, if you look at how both block and local_action appear in playbooks they look more like modules and less like keywords. For the local_action one in particular as it is basically the very same syntax as for modules (short and long), it is basically syntactically equal to ansible.builtin.shell and such.

e.g.

- name: Return motd to registered var
  ansible.builtin.command: cat /etc/motd
  register: mymotd
- name: Return motd of controller to registered var
  local_action: ansible.builtin.command cat /etc/motd
  register: mymotd


- name: Return motd to registered var
  ansible.builtin.command:
    argv:
      - cat
      - /etc/motd
  register: mymotd
- name: Return motd of controller to registered var
  local_action:
    module: ansible.builtin.command
    argv:
      - cat
      - /etc/motd
  register: mymotd

The section within the "ansible.builtin" collection index could be as short as:

# Differentiated from
Some builtin constructs look like modules but are language keywords.
Thereby modules within ansible.builtin should not be confused with them.
Commonly these keywords are confused for ansible.builtin modules:
* local_action (with link to page)
* block (with link to page)