Backport/2.8/docs modules omnibus (#56316)

* Update gcp_container_cluster_facts.py (#55475) : 'state' is not a supported parameter in this module

(cherry picked from commit 8c7e38af62)

* Update win_dns_record.py (#55378): Update examples to show values are strings.

(cherry picked from commit 3fd27f0cac)

* sensu_subscription very minor docstring typo (#55675)

(cherry picked from commit 2cfaf6e80a)

* Update win_domain_group_membership.py (#55594): add notes regarding a computer object and fixing a typo

(cherry picked from commit 3f0900f504)

* hcloud_server: clarify further for usage of `ssh_keys` (#55713)

(cherry picked from commit 6e9379fe11)

* Fix template lookup description (#55557): describe that it returns template content with substituted variables.

(cherry picked from commit 9c038b210b)

* Update ec2_eip_facts.py (#53040): Add several additional examples showing how to filter on tag, how to filter on the EIP allocation id, and how to set a fact using the output.

(cherry picked from commit 1e2cbefac0)

* Update ali_instance_facts examples in documentation (#55760) (#55803)

(cherry picked from commit 357dafffa4)

* Update setup.py (#55871): adds a note on privileges needed on BSD systems to use dmidecode

(cherry picked from commit c181e567a1)

* Remove illegal basic provisioning example (#55892): The bare minimum example in the docs (i.e. only supplying name, state, and cluster) results in the error `state is present but all of the following are missing: task_definition, desired_count`.

(cherry picked from commit c195645575)

* clarify docs for rel src state hard (#55972)

(cherry picked from commit 0b002203b4)

* correct method docs (#55961)

(cherry picked from commit ea57377ddf)

* Update sample (#55654): Correct logConfiguration example on the ecs_taskdefinition module.

(cherry picked from commit 23ddc7738b)

* add missing exported state do doc string (#56109)

(cherry picked from commit ba9f0d53b2)

* package_facts: Trivial docs cleanup (#56015): use
the current YAML style and remove unnecessary quotes around `auto`.

Signed-off-by: Major Hayden <major@redhat.com>
(cherry picked from commit 93d24efe37)

* Update include_role description (#56001) to discuss tasks: use

(cherry picked from commit 8cb76408d3)

* Sync required flags from argument_spec to docs (#56121): arguments for certificate, private_key and password were marked as required in the ArgumentSpec, but not in the documentation. 

(cherry picked from commit 6b474a1ecd)

* updated ec2.py to describe required parameters (#56197): for each option for `state`

(cherry picked from commit 5346a5cdac)

* Update os_image documentation (#49705) to show auth details

(cherry picked from commit f5326aa6cd)

lib/ansible/modules/cloud/alicloud/ali_instance_facts.py

@@ -72,15 +72,26 @@ EXAMPLES = '''
   tasks:
     - name: Find all instances in the specified region
       ali_instance_facts:
+        alicloud_access_key: '{{ alicloud_access_key }}'
+        alicloud_secret_key: '{{ alicloud_secret_key }}'
+        alicloud_region: '{{ alicloud_region }}'
       register: all_instances
+
     - name: Find all instances based on the specified ids
       ali_instance_facts:
+        alicloud_access_key: '{{ alicloud_access_key }}'
+        alicloud_secret_key: '{{ alicloud_secret_key }}'
+        alicloud_region: '{{ alicloud_region }}'
         instance_ids:
           - "i-35b333d9"
           - "i-ddav43kd"
       register: instances_by_ids
+
     - name: Find all instances based on the specified names/name-prefixes
       ali_instance_facts:
+        alicloud_access_key: '{{ alicloud_access_key }}'
+        alicloud_secret_key: '{{ alicloud_secret_key }}'
+        alicloud_region: '{{ alicloud_region }}'
         instance_names:
           - "ecs_instance-1"
           - "ecs_instance_2"

lib/ansible/modules/cloud/amazon/ec2.py

@@ -195,11 +195,11 @@ options:
   state:
     version_added: "1.3"
     description:
-      - create, terminate, start, stop or restart instances.
-        The state 'restarted' was added in 2.2
-    required: false
+      - Create, terminate, start, stop or restart instances. The state 'restarted' was added in Ansible 2.2.
+      - When 'absent', I(instance_ids) is required.
+      - When 'running', 'stopped' and 'restarted', I(instance_ids) or I(instance_tags) is required.
     default: 'present'
-    choices: ['present', 'absent', 'running', 'restarted', 'stopped']
+    choices: ['absent', 'present', 'restarted', 'running', 'stopped']
     type: str
   volumes:
     version_added: "1.5"

lib/ansible/modules/cloud/amazon/ec2_eip_facts.py

@@ -52,6 +52,24 @@ EXAMPLES = '''
          - i-987654321
   register: my_vms_eips
 
+# List all EIP addresses using the 'Name' tag as a filter.
+- ec2_eip_facts:
+    filters:
+      tag:Name: www.example.com
+  register: my_vms_eips
+
+# List all EIP addresses using the Allocation-id as a filter
+- ec2_eip_facts:
+    filters:
+      allocation-id: eipalloc-64de1b01
+  register: my_vms_eips
+
+# Set the variable eip_alloc to the value of the first allocation_id
+# and set the variable my_pub_ip to the value of the first public_ip
+- set_fact:
+    eip_alloc: my_vms_eips.addresses[0].allocation_id
+    my_pub_ip: my_vms_eips.addresses[0].public_ip
+
 '''
 
 

lib/ansible/modules/cloud/amazon/ecs_service.py

@@ -160,6 +160,8 @@ extends_documentation_fragment:
 
 EXAMPLES = '''
 # Note: These examples do not set authentication details, see the AWS Guide for details.
+
+# Basic provisioning example
 - ecs_service:
     state: present
     name: console-test-service
@@ -167,12 +169,6 @@ EXAMPLES = '''
     task_definition: 'new_cluster-task:1'
     desired_count: 0
 
-# Basic provisioning example
-- ecs_service:
-    name: default
-    state: present
-    cluster: new_cluster
-
 - name: create ECS service on VPC network
   ecs_service:
     state: present

lib/ansible/modules/cloud/amazon/ecs_taskdefinition.py

@@ -120,8 +120,9 @@ EXAMPLES = '''
       logConfiguration:
         logDriver: awslogs
         options:
-          awslogs-group: ecs
+          awslogs-group: /ecs/test-cluster-taskdef
           awslogs-region: us-west-2
+          awslogs-stream-prefix: ecs
     - name: busybox
       command:
         - >

lib/ansible/modules/cloud/google/gcp_container_cluster_facts.py

@@ -58,7 +58,6 @@ EXAMPLES = '''
     project: test_project
     auth_kind: serviceaccount
     service_account_file: "/tmp/auth.pem"
-    state: facts
 '''
 
 RETURN = '''

lib/ansible/modules/cloud/hcloud/hcloud_server.py

@@ -46,7 +46,9 @@ options:
         type: str
     ssh_keys:
         description:
-            - List of SSH Keys Names
+            - List of SSH key names
+            - The key names correspond to the SSH keys configured for your
+              Hetzner Cloud account access.
         type: list
     volumes:
         description:
@@ -117,7 +119,7 @@ EXAMPLES = """
     image: ubuntu-18.04
     location: fsn1
     ssh_keys:
-      - my-ssh-key
+      - me@myorganisation
     state: present
 
 - name: Resize an existing server

lib/ansible/modules/cloud/openstack/os_image.py

@@ -91,6 +91,8 @@ EXAMPLES = '''
       username: admin
       password: passme
       project_name: admin
+      os_user_domain_name: Default
+      os_project_domain_name: Default
     name: cirros
     container_format: bare
     disk_format: qcow2

lib/ansible/modules/cloud/ovirt/ovirt_disk.py

@@ -37,8 +37,8 @@ options:
             - "ID of the Virtual Machine to manage. Either C(vm_id) or C(vm_name) is required if C(state) is I(attached) or I(detached)."
     state:
         description:
-            - "Should the Virtual Machine disk be present/absent/attached/detached."
-        choices: ['present', 'absent', 'attached', 'detached']
+            - "Should the Virtual Machine disk be present/absent/attached/detached/exported."
+        choices: ['present', 'absent', 'attached', 'detached', 'exported']
         default: 'present'
     download_image_path:
         description:

lib/ansible/modules/files/file.py

@@ -52,7 +52,8 @@ options:
     description:
     - Path of the file to link to.
     - This applies only to C(state=link) and C(state=hard).
-    - Will accept absolute, relative and non-existing paths.
+    - Will accept absolute and non-existing paths.
+    - Will accept relative paths unless state=hard.
     - Relative paths are relative to the file being created (C(path)) which is how
       the Unix command C(ln -s SRC DEST) treats relative paths.
     type: path

lib/ansible/modules/monitoring/sensu_subscription.py

@@ -49,7 +49,7 @@ author: Anders Ingemann (@andsens)
 
 RETURN = '''
 reasons:
-    description: the reasons why the moule changed or did not change something
+    description: the reasons why the module changed or did not change something
     returned: success
     type: list
     sample: ["channel subscription was absent and state is `present'"]

lib/ansible/modules/packaging/os/package_facts.py

@@ -44,12 +44,13 @@ author:
 '''
 
 EXAMPLES = '''
-- name: get the rpm package facts
+- name: Gather the rpm package facts
   package_facts:
-    manager: "auto"
+    manager: auto
 
-- name: show them
-  debug: var=ansible_facts.packages
+- name: Print the rpm package facts
+  debug:
+    var: ansible_facts.packages
 
 '''
 

lib/ansible/modules/system/java_keystore.py

@@ -28,15 +28,15 @@ options:
     certificate:
         description:
           - Certificate that should be used to create the key store.
-        required: false
+        required: true
     private_key:
         description:
           - Private key that should be used to create the key store.
-        required: false
+        required: true
     password:
         description:
           - Password that should be used to secure the key store.
-        required: false
+        required: true
     dest:
         description:
           - Absolute path where the jks should be generated.

lib/ansible/modules/system/setup.py

@@ -82,6 +82,7 @@ notes:
       output of your scripts.
       This option was added in Ansible 2.1.
     - This module is also supported for Windows targets.
+    - This module should be run with elevated priviliges on BSD systems to gather facts like ansible_product_version.
 author:
     - "Ansible Core Team"
     - "Michael DeHaan"

lib/ansible/modules/utilities/logic/include_role.py

@@ -19,16 +19,17 @@ author: Ansible Core Team (@ansible)
 module: include_role
 short_description: Load and execute a role
 description:
-  - Loads and executes a role as a task dynamically.
-  - This frees roles from the C(roles:) directive and allows them to be treated more as tasks.
-  - Unlike M(import_role), most keywords, including loop, with_items, and conditionals, apply to this statement.
-  - The do until loop is not supported on M(include_role).
+  - Dynamically loads and executes a specified role as a task.
+  - May be used only where Ansible tasks are allowed - inside C(pre_tasks), C(tasks), or C(post_tasks) playbook objects, or as a task inside a role.
+  - Task-level keywords, loops, and conditionals apply only to the C(include_role) statement itself.
+  - To apply keywords to the tasks within the role, pass them using the C(apply) option or use M(import_role) instead.
+  - Ignores some keywords, like C(until) and C(retries).
   - This module is also supported for Windows targets.
 version_added: "2.2"
 options:
   apply:
     description:
-      - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to the tasks within the include.
+      - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to all tasks within the included role.
     version_added: '2.7'
   name:
     description:

lib/ansible/modules/windows/win_dns_record.py

@@ -71,17 +71,17 @@ options:
 EXAMPLES = r'''
 - name: Create database server alias
   win_dns_record:
-    name: db1
-    type: CNAME
-    value: cgyl1404p.amer.example.com
-    zone: amer.example.com
+    name: "db1"
+    type: "CNAME"
+    value: "cgyl1404p.amer.example.com"
+    zone: "amer.example.com"
 
 - name: Remove static record
   win_dns_record:
-    name: db1
-    type: A
+    name: "db1"
+    type: "A"
     state: absent
-    zone: amer.example.com
+    zone: "amer.example.com"
 '''
 
 RETURN = r'''

lib/ansible/modules/windows/win_domain_group_membership.py

@@ -25,7 +25,8 @@ options:
   members:
     description:
       - A list of members to ensure are present/absent from the group.
-      - The given names must be a SmaAccountName of a user, group, service account, or computer
+      - The given names must be a SamAccountName of a user, group, service account, or computer.
+      - For computers, you must add "$" after the name; for example, to add "Mycomputer" to a group, use "Mycomputer$" as the member.
     type: list
     required: yes
   state:

lib/ansible/playbook/attribute.py

@@ -52,7 +52,8 @@ class Attribute:
         :kwarg isa: The type of the attribute.  Allowable values are a string
             representation of any yaml basic datatype, python class, or percent.
             (Enforced at post-validation time).
-        :kwarg private: (not used)
+        :kwarg private: Hides the attribute from being documented.
+                        TODO: it should also should prevent it from being user settable
         :kwarg default: Default value if unspecified in the YAML document.
         :kwarg required: Whether or not the YAML document must contain this field.
             If the attribute is None when post-validated, an error will be raised.

lib/ansible/plugins/doc_fragments/openstack.py

@@ -24,7 +24,8 @@ options:
       - Dictionary containing auth information as needed by the cloud's auth
         plugin strategy. For the default I(password) plugin, this would contain
         I(auth_url), I(username), I(password), I(project_name) and any
-        information about domains if the cloud supports them. For other plugins,
+        information about domains (for example, I(os_user_domain_name) or I(os_project_domain_name)) if the cloud supports them.
+        For other plugins,
         this param will need to contain whatever parameters that auth plugin
         requires. This parameter is not needed if a named cloud is provided or
         OpenStack OS_* environment variables are present.

lib/ansible/plugins/lookup/template.py

@@ -11,7 +11,7 @@ DOCUMENTATION = """
     version_added: "0.9"
     short_description: retrieve contents of file after templating with Jinja2
     description:
-      - this is mostly a noop, to be used as a with_list loop when you do not want the content transformed in any way.
+      - Returns a list of strings; for each template in the list of templates you pass in, returns a string containing the results of processing that template.
     options:
       _terms:
         description: list of files to template