New module/plugin documentation fields

[bcoca]

Proposal: Properties

Author: Brian Coca <@bcoca> IRC: bcoca

Date: 2017/88/99

• Status: New
• Proposal type: docs
• Targeted Release: Future release
• Estimated time to implement: hours

Motivation

Clarify and centralize documentation for special behaviours of modules and plugins.

Problems

• Many of the modules and plugins don't document certain common special behaviors (i.e bypassing host loop)
• Those that do use different language and position it in notes or descriptions mostly in random fashion.
• This is a LOT of repeat text

Solution proposal

New 'properties' field in documentation that is a list of 'special properties and/or behaviors' that this module/plugin exhibit.

in plugin docs:

features:
  - name: bypass_host_loop
  - name: no_connection
  - name: check_mode
  - name: diff_mode
    version_added: "2.4"
limitations:
 - name: remote_connections
 - name: async

These then can be mapped to a SINGLE description of what the property means for this plugin, both for ansible-doc and docs website.

Also need to categorize by things that are expected to be supported by default (would have to declare limitation) vs those that are optional (declared in feature).

descriptions.yml:

async: running in asynchronous mode (via async keyword).

bypass_host_loop: behaves as if it had `run_once: true`, which means it won't loop per host but only execute once, any variables will be from the 'first active host' to get to this point. But results are applied to all.

check_mode: running in check mode and reporting on expected change state but not changing things.

diff_mode: reporting expected/transpired changes with before/after differences when diff mode is active.

facts: this action returns ansible_facts

remote_connection: do not connect to the target and solely executes on the controller. # debug is good example

delegation: applies to delegate_to and/or delegate_facts

One variation we can have is define all keywords and allow for a no_ prefix to be a modifier and a single field, instead of 2.

[abadger]

Note, rst can include common text in multiple places. UX-wise, that's probably how we should implement this.

[bcoca]

just need to list the properties in each plugin, then representing the 'meaning' in both html/ansible-doc can easily be substituted. We already do this with supported_by.

[dagwieers]

Other properties:

• check_mode support
• is_idempotent (or is not idempotent)
• updates_facts
• supports_delegation (or do not support delegation)

Some of these properties should probably be default unless unset.

[phips]

I know The I Word gets used a lot when talking about config management, but I've long said we shouldn't use it with Ansible. Why? Because half the people in IT can't even pronounce it correctly, let alone tell you what it means. It's a typical case of IT trying to sound clever, rather than being helpful (the term is borrowed from maths, and IMHO shoe horned incorrectly into this use case). Ansible's core principle is simplicity, and to that end I've always preferred to use 'plain english'. What we're talking about is desired state. I'd really prefer we didn't use 'idempotent' anywhere, but at the end of the day this is just my opinion and although I can't tell you not to use it, I appeal to your helpful natures and to discard the word from use with Ansible 😄

[felixfontein]

I like this proposal. I'm wondering a bit how it would work in the collection world: would Ansible determine the possible values (and descriptions), or could every collection do that by themselves? Or would there be Ansible default values which could / cannot be changed, and more can be added per collection?

[bcoca]

i would allow 'any values', but if they don't match 'known values' by ansible/docsite, those won't get 'explanation'

[gregdek]

Should we want to add an "orphaned" field, this might be the right place to do it.

[felixfontein]

@bcoca created a first implementation in ansible/ansible#73707! 🎉

[bcoca]

closing as above is merged, this will probably have more added over time, but the basic parts of the proposal have been met.