Review documentation of individual plugins

[happz]

Rules

General ones

• design the docstrings and help texts as if they are destined to be rendered by Sphinx, i.e. make use of ReST goodies: literals for literals - metavars, values, envvar names, commands, keys, etc., code-block for blocks of code or examples. It leads to better HTML docs and we will have a nice CLI renderer as well, there is no need to compromise for the sake of CLI.
• use full sentences, i.e. capital letters at the beginning & a full stop at the end.
• use Python's multiline strings rather than joining multiple strings.

Plugin docs

• plugin docstring provides the bulk of its CLI help and HTML documentation. It should describe what the plugin does.
• less than trivial use cases and keys deserve an example or two.
• unless there's an important difference, describe the plugin's configuration in terms of fmf rather than CLI. It's easy to map fmf to CLI options, fmf makes a better example for someone writing fmf files.

Plugin fields

• when referring to fields in user-facing docs, speak about "keys", i.e. "playbook key of prepare/ansible plugin". Keys are mapped 1:1 to CLI options, but let's make sure we avoid "fields", "settings" and other synonyms.
• metavar should represent the semantic of the expected value, i.e. --file PATH is better than --file FILE, --playbook PATH|URL is better than --playbook PLAYBOOK.
• if there's a default value, it belongs to the default= key of field(), and the help text should not mention it as the "Default is ..." can be easily added automatically and rendered correctly with show_default=True.
• when showing an example of how something is expressed, include also an example for the command line:

  Run a single playbook on the guest:
  
  .. code-block:: yaml
  
      prepare:
          how: ansible
          playbook: ansible/packages.yml
  
  .. code-block:: shell
  
      prepare --how ansible --playbook ansible/packages.yml

  Do not use :caption: directive, it is parsed by Sphinx only and docutils package cannot handle it.

Pull requests

• discover
  • fmf
  • shell
• execute
  • internal
  • upgrade
• finish
  • ansible
  • shell
• prepare
  • ansible Polish prepare/ansible documentation #2824
  • feature
  • install
  • shell
• provision
  • artemis
  • connect
  • local
  • mrack
  • podman
  • testcloud
• report
  • display
  • html
  • junit
  • polarion
  • reportportal
• checks
  • avc
  • dmesg
  • watchdog