modules: fix documentation formatting (#72737) (#72850)

(cherry picked from commit ebd8c101fd)

lib/ansible/modules/cron.py

@@ -33,8 +33,8 @@ options:
   name:
     description:
       - Description of a crontab entry or, if env is set, the name of environment variable.
-      - Required if C(state=absent).
-      - Note that if name is not set and C(state=present), then a
+      - Required if I(state=absent).
+      - Note that if name is not set and I(state=present), then a
         new crontab entry will always be created, regardless of existing ones.
       - This parameter will always be required in future releases.
     type: str
@@ -47,7 +47,7 @@ options:
     description:
       - The command to execute or, if env is set, the value of environment variable.
       - The command should not contain line breaks.
-      - Required if C(state=present).
+      - Required if I(state=present).
     type: str
     aliases: [ value ]
   state:
@@ -60,10 +60,10 @@ options:
     description:
       - If specified, uses this file instead of an individual user's crontab.
       - If this is a relative path, it is interpreted with respect to I(/etc/cron.d).
-      - If it is absolute, it will typically be I(/etc/crontab).
+      - If it is absolute, it will typically be C(/etc/crontab).
       - Many linux distros expect (and some require) the filename portion to consist solely
         of upper- and lower-case letters, digits, underscores, and hyphens.
-      - To use the C(cron_file) parameter you must specify the C(user) as well.
+      - To use the I(cron_file) parameter you must specify the I(user) as well.
     type: str
   backup:
     description:
@@ -73,34 +73,34 @@ options:
     default: no
   minute:
     description:
-      - Minute when the job should run ( 0-59, *, */2, etc )
+      - Minute when the job should run (C(0-59), C(*), C(*/2), and so on).
     type: str
     default: "*"
   hour:
     description:
-      - Hour when the job should run ( 0-23, *, */2, etc )
+      - Hour when the job should run (C(0-23), C(*), C(*/2), and so on).
     type: str
     default: "*"
   day:
     description:
-      - Day of the month the job should run ( 1-31, *, */2, etc )
+      - Day of the month the job should run (C(1-31), C(*), C(*/2), and so on).
     type: str
     default: "*"
     aliases: [ dom ]
   month:
     description:
-      - Month of the year the job should run ( 1-12, *, */2, etc )
+      - Month of the year the job should run (C(1-12), C(*), C(*/2), and so on).
     type: str
     default: "*"
   weekday:
     description:
-      - Day of the week that the job should run ( 0-6 for Sunday-Saturday, *, etc )
+      - Day of the week that the job should run (C(0-6) for Sunday-Saturday, C(*), and so on).
     type: str
     default: "*"
     aliases: [ dow ]
   reboot:
     description:
-      - If the job should be run at reboot. This option is deprecated. Users should use special_time.
+      - If the job should be run at reboot. This option is deprecated. Users should use I(special_time).
     version_added: "1.0"
     type: bool
     default: no
@@ -113,7 +113,7 @@ options:
   disabled:
     description:
       - If the job should be disabled (commented out) in the crontab.
-      - Only has effect if C(state=present).
+      - Only has effect if I(state=present).
     type: bool
     default: no
     version_added: "2.0"
@@ -121,66 +121,68 @@ options:
     description:
       - If set, manages a crontab's environment variable.
       - New variables are added on top of crontab.
-      - C(name) and C(value) parameters are the name and the value of environment variable.
+      - I(name) and I(value) parameters are the name and the value of environment variable.
     type: bool
     default: false
     version_added: "2.1"
   insertafter:
     description:
-      - Used with C(state=present) and C(env).
+      - Used with I(state=present) and I(env).
       - If specified, the environment variable will be inserted after the declaration of specified environment variable.
     type: str
     version_added: "2.1"
   insertbefore:
     description:
-      - Used with C(state=present) and C(env).
+      - Used with I(state=present) and I(env).
       - If specified, the environment variable will be inserted before the declaration of specified environment variable.
     type: str
     version_added: "2.1"
 requirements:
   - cron (or cronie on CentOS)
 author:
-    - Dane Summers (@dsummersl)
-    - Mike Grozak (@rhaido)
-    - Patrick Callahan (@dirtyharrycallahan)
-    - Evan Kaufman (@EvanK)
-    - Luca Berruti (@lberruti)
+  - Dane Summers (@dsummersl)
+  - Mike Grozak (@rhaido)
+  - Patrick Callahan (@dirtyharrycallahan)
+  - Evan Kaufman (@EvanK)
+  - Luca Berruti (@lberruti)
+notes:
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = r'''
 - name: Ensure a job that runs at 2 and 5 exists. Creates an entry like "0 5,2 * * ls -alh > /dev/null"
-  cron:
+  ansible.builtin.cron:
     name: "check dirs"
     minute: "0"
     hour: "5,2"
     job: "ls -alh > /dev/null"
 
 - name: 'Ensure an old job is no longer present. Removes any job that is prefixed by "#Ansible: an old job" from the crontab'
-  cron:
+  ansible.builtin.cron:
     name: "an old job"
     state: absent
 
 - name: Creates an entry like "@reboot /some/job.sh"
-  cron:
+  ansible.builtin.cron:
     name: "a job for reboot"
     special_time: reboot
     job: "/some/job.sh"
 
 - name: Creates an entry like "PATH=/opt/bin" on top of crontab
-  cron:
+  ansible.builtin.cron:
     name: PATH
     env: yes
     job: /opt/bin
 
 - name: Creates an entry like "APP_HOME=/srv/app" and insert it after PATH declaration
-  cron:
+  ansible.builtin.cron:
     name: APP_HOME
     env: yes
     job: /srv/app
     insertafter: PATH
 
 - name: Creates a cron file under /etc/cron.d
-  cron:
+  ansible.builtin.cron:
     name: yum autoupdate
     weekday: "2"
     minute: "0"
@@ -190,18 +192,20 @@ EXAMPLES = r'''
     cron_file: ansible_yum-autoupdate
 
 - name: Removes a cron file from under /etc/cron.d
-  cron:
+  ansible.builtin.cron:
     name: "yum autoupdate"
     cron_file: ansible_yum-autoupdate
     state: absent
 
 - name: Removes "APP_HOME" environment variable from crontab
-  cron:
+  ansible.builtin.cron:
     name: APP_HOME
     env: yes
     state: absent
 '''
 
+RETURN = r'''#'''
+
 import os
 import platform
 import pwd

lib/ansible/modules/debconf.py

@@ -23,6 +23,7 @@ notes:
       installed to see questions/settings available.
     - Some distros will always record tasks involving the setting of passwords as changed. This is due to debconf-get-selections masking passwords.
     - It is highly recommended to add I(no_log=True) to task while handling sensitive information using this module.
+    - Supports C(check_mode).
 requirements:
 - debconf
 - debconf-utils
@@ -61,32 +62,32 @@ author:
 
 EXAMPLES = r'''
 - name: Set default locale to fr_FR.UTF-8
-  debconf:
+  ansible.builtin.debconf:
     name: locales
     question: locales/default_environment_locale
     value: fr_FR.UTF-8
     vtype: select
 
 - name: Set to generate locales
-  debconf:
+  ansible.builtin.debconf:
     name: locales
     question: locales/locales_to_be_generated
     value: en_US.UTF-8 UTF-8, fr_FR.UTF-8 UTF-8
     vtype: multiselect
 
 - name: Accept oracle license
-  debconf:
+  ansible.builtin.debconf:
     name: oracle-java7-installer
     question: shared/accepted-oracle-license-v1-1
     value: 'true'
     vtype: select
 
 - name: Specifying package you can register/return the list of questions and current values
-  debconf:
+  ansible.builtin.debconf:
     name: tzdata
 
 - name: Pre-configure tripwire site passphrase
-  debconf:
+  ansible.builtin.debconf:
     name: tripwire
     question: tripwire/site-passphrase
     value: "{{ site_passphrase }}"
@@ -94,6 +95,8 @@ EXAMPLES = r'''
   no_log: True
 '''
 
+RETURN = r'''#'''
+
 from ansible.module_utils._text import to_text
 from ansible.module_utils.basic import AnsibleModule
 

lib/ansible/modules/debug.py

@@ -49,29 +49,27 @@ author:
 '''
 
 EXAMPLES = r'''
-# Example that prints the loopback address and gateway for each host
-- debug:
-    msg: System {{ inventory_hostname }} has uuid {{ ansible_product_uuid }}
-
-- debug:
+- name: Print the gateway for each host when defined
+  ansible.builtin.debug:
     msg: System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}
   when: ansible_default_ipv4.gateway is defined
 
-# Example that prints return information from the previous task
-- shell: /usr/bin/uptime
+- name: Get uptime information
+  ansible.builtin.shell: /usr/bin/uptime
   register: result
 
-- debug:
+- name: Print return information from the previous task
+  ansible.builtin.debug:
     var: result
     verbosity: 2
 
 - name: Display all variables/facts known for a host
-  debug:
+  ansible.builtin.debug:
     var: hostvars[inventory_hostname]
     verbosity: 4
 
-# Example that prints two lines of messages, but only if there is an environment value set
-- debug:
+- name: Prints two lines of messages, but only if there is an environment value set
+  ansible.builtin.debug:
     msg:
     - "Provisioning based on YOUR_KEY which is: {{ lookup('env', 'YOUR_KEY') }}"
     - "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."

lib/ansible/modules/fetch.py

@@ -71,6 +71,7 @@ notes:
   also explicitly set C(fail_on_missing) to C(no) to get the
   non-failing behaviour.
 - This module is also supported for Windows targets.
+- Supports C(check_mode).
 seealso:
 - module: ansible.builtin.copy
 - module: ansible.builtin.slurp
@@ -81,24 +82,24 @@ author:
 
 EXAMPLES = r'''
 - name: Store file into /tmp/fetched/host.example.com/tmp/somefile
-  fetch:
+  ansible.builtin.fetch:
     src: /tmp/somefile
     dest: /tmp/fetched
 
 - name: Specifying a path directly
-  fetch:
+  ansible.builtin.fetch:
     src: /tmp/somefile
     dest: /tmp/prefix-{{ inventory_hostname }}
     flat: yes
 
 - name: Specifying a destination path
-  fetch:
+  ansible.builtin.fetch:
     src: /tmp/uniquefile
     dest: /tmp/special/
     flat: yes
 
 - name: Storing in a path relative to the playbook
-  fetch:
+  ansible.builtin.fetch:
     src: /tmp/uniquefile
     dest: special/prefix-{{ inventory_hostname }}
     flat: yes

lib/ansible/modules/group.py

@@ -62,20 +62,21 @@ seealso:
 - module: ansible.windows.win_group
 author:
 - Stephen Fromm (@sfromm)
+notes:
+- Supports C(check_mode).
 '''
 
 EXAMPLES = '''
 - name: Ensure group "somegroup" exists
-  group:
+  ansible.builtin.group:
     name: somegroup
     state: present
 
 - name: Ensure group "docker" exists with correct gid
-  group:
+  ansible.builtin.group:
     name: docker
     state: present
     gid: 1750
-
 '''
 
 RETURN = r'''
@@ -85,17 +86,17 @@ gid:
   type: int
   sample: 1001
 name:
-  description: Group name
+  description: Group name.
   returned: always
   type: str
   sample: users
 state:
-  description: Whether the group is present or not
+  description: Whether the group is present or not.
   returned: always
   type: str
   sample: 'absent'
 system:
-  description: Whether the group is a system group or not
+  description: Whether the group is a system group or not.
   returned: When C(state) is 'present'
   type: bool
   sample: False

lib/ansible/modules/lineinfile.py

@@ -125,6 +125,7 @@ extends_documentation_fragment:
     - validate
 notes:
   - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well.
+  - Supports C(check_mode).
 seealso:
 - module: ansible.builtin.blockinfile
 - module: ansible.builtin.copy
@@ -140,19 +141,19 @@ author:
 EXAMPLES = r'''
 # NOTE: Before 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
 - name: Ensure SELinux is set to enforcing mode
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /etc/selinux/config
     regexp: '^SELINUX='
     line: SELINUX=enforcing
 
 - name: Make sure group wheel is not in the sudoers configuration
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /etc/sudoers
     state: absent
     regexp: '^%wheel'
 
 - name: Replace a localhost entry with our own
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /etc/hosts
     regexp: '^127\.0\.0\.1'
     line: 127.0.0.1 localhost
@@ -161,28 +162,28 @@ EXAMPLES = r'''
     mode: '0644'
 
 - name: Ensure the default Apache port is 8080
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /etc/httpd/conf/httpd.conf
     regexp: '^Listen '
     insertafter: '^#Listen '
     line: Listen 8080
 
 - name: Ensure we have our own comment added to /etc/services
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /etc/services
     regexp: '^# port for http'
     insertbefore: '^www.*80/tcp'
     line: '# port for http by default'
 
 - name: Add a line to a file if the file does not exist, without passing regexp
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /tmp/testfile
     line: 192.168.1.99 foo.lab.net foo
     create: yes
 
 # NOTE: Yaml requires escaping backslashes in double quotes but not in single quotes
 - name: Ensure the JBoss memory settings are exactly as needed
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /opt/jboss-as/bin/standalone.conf
     regexp: '^(.*)Xms(\d+)m(.*)$'
     line: '\1Xms${xms}m\3'
@@ -190,7 +191,7 @@ EXAMPLES = r'''
 
 # NOTE: Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs.
 - name: Validate the sudoers file before saving
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /etc/sudoers
     state: present
     regexp: '^%ADMIN ALL='
@@ -199,13 +200,15 @@ EXAMPLES = r'''
 
 # See https://docs.python.org/3/library/re.html for further details on syntax
 - name: Use backrefs with alternative group syntax to avoid conflicts with variable values
-  lineinfile:
+  ansible.builtin.lineinfile:
     path: /tmp/config
     regexp: ^(host=).*
     line: \g<1>{{ hostname }}
     backrefs: yes
 '''
 
+RETURN = r'''#'''
+
 import os
 import re
 import tempfile

lib/ansible/modules/ping.py

@@ -15,12 +15,12 @@ module: ping
 version_added: historical
 short_description: Try to connect to host, verify a usable python and return C(pong) on success
 description:
-   - A trivial test module, this module always returns C(pong) on successful
-     contact. It does not make sense in playbooks, but it is useful from
-     C(/usr/bin/ansible) to verify the ability to login and that a usable Python is configured.
-   - This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node.
-   - For Windows targets, use the M(ansible.windows.win_ping) module instead.
-   - For Network targets, use the M(ansible.netcommon.net_ping) module instead.
+  - A trivial test module, this module always returns C(pong) on successful
+    contact. It does not make sense in playbooks, but it is useful from
+    C(/usr/bin/ansible) to verify the ability to login and that a usable Python is configured.
+  - This is NOT ICMP ping, this is just a trivial test module that requires Python on the remote-node.
+  - For Windows targets, use the M(ansible.windows.win_ping) module instead.
+  - For Network targets, use the M(ansible.netcommon.net_ping) module instead.
 options:
   data:
     description:
@@ -29,11 +29,13 @@ options:
     type: str
     default: pong
 seealso:
-- module: ansible.netcommon.net_ping
-- module: ansible.windows.win_ping
+  - module: ansible.netcommon.net_ping
+  - module: ansible.windows.win_ping
 author:
-    - Ansible Core Team
-    - Michael DeHaan
+  - Ansible Core Team
+  - Michael DeHaan
+notes:
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = '''
@@ -41,16 +43,16 @@ EXAMPLES = '''
 # ansible webservers -m ping
 
 - name: Example from an Ansible Playbook
-  ping:
+  ansible.builtin.ping:
 
 - name: Induce an exception to see what happens
-  ping:
+  ansible.builtin.ping:
     data: crash
 '''
 
 RETURN = '''
 ping:
-    description: value provided with the data parameter
+    description: Value provided with the data parameter.
     returned: success
     type: str
     sample: pong

lib/ansible/modules/replace.py

@@ -95,24 +95,25 @@ notes:
     previous incorrect behavior, you may be need to adjust your tasks.
     See U(https://github.com/ansible/ansible/issues/31354) for details.
   - Option I(follow) has been removed in Ansible 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense.
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = r'''
 - name: Before Ansible 2.3, option 'dest', 'destfile' or 'name' was used instead of 'path'
-  replace:
+  ansible.builtin.replace:
     path: /etc/hosts
     regexp: '(\s+)old\.host\.name(\s+.*)?$'
     replace: '\1new.host.name\2'
 
 - name: Replace after the expression till the end of the file (requires Ansible >= 2.4)
-  replace:
+  ansible.builtin.replace:
     path: /etc/apache2/sites-available/default.conf
     after: 'NameVirtualHost [*]'
     regexp: '^(.+)$'
     replace: '# \1'
 
 - name: Replace before the expression till the begin of the file (requires Ansible >= 2.4)
-  replace:
+  ansible.builtin.replace:
     path: /etc/apache2/sites-available/default.conf
     before: '# live site config'
     regexp: '^(.+)$'
@@ -121,7 +122,7 @@ EXAMPLES = r'''
 # Prior to Ansible 2.7.10, using before and after in combination did the opposite of what was intended.
 # see https://github.com/ansible/ansible/issues/31354 for details.
 - name: Replace between the expressions (requires Ansible >= 2.4)
-  replace:
+  ansible.builtin.replace:
     path: /etc/hosts
     after: '<VirtualHost [*]>'
     before: '</VirtualHost>'
@@ -129,7 +130,7 @@ EXAMPLES = r'''
     replace: '# \1'
 
 - name: Supports common file attributes
-  replace:
+  ansible.builtin.replace:
     path: /home/jdoe/.ssh/known_hosts
     regexp: '^old\.host\.name[^\n]*\n'
     owner: jdoe
@@ -137,34 +138,36 @@ EXAMPLES = r'''
     mode: '0644'
 
 - name: Supports a validate command
-  replace:
+  ansible.builtin.replace:
     path: /etc/apache/ports
     regexp: '^(NameVirtualHost|Listen)\s+80\s*$'
     replace: '\1 127.0.0.1:8080'
     validate: '/usr/sbin/apache2ctl -f %s -t'
 
 - name: Short form task (in ansible 2+) necessitates backslash-escaped sequences
-  replace: path=/etc/hosts regexp='\\b(localhost)(\\d*)\\b' replace='\\1\\2.localdomain\\2 \\1\\2'
+  ansible.builtin.replace: path=/etc/hosts regexp='\\b(localhost)(\\d*)\\b' replace='\\1\\2.localdomain\\2 \\1\\2'
 
 - name: Long form task does not
-  replace:
+  ansible.builtin.replace:
     path: /etc/hosts
     regexp: '\b(localhost)(\d*)\b'
     replace: '\1\2.localdomain\2 \1\2'
 
 - name: Explicitly specifying positional matched groups in replacement
-  replace:
+  ansible.builtin.replace:
     path: /etc/ssh/sshd_config
     regexp: '^(ListenAddress[ ]+)[^\n]+$'
     replace: '\g<1>0.0.0.0'
 
 - name: Explicitly specifying named matched groups
-  replace:
+  ansible.builtin.replace:
     path: /etc/ssh/sshd_config
     regexp: '^(?P<dctv>ListenAddress[ ]+)(?P<host>[^\n]+)$'
     replace: '#\g<dctv>\g<host>\n\g<dctv>0.0.0.0'
 '''
 
+RETURN = r'''#'''
+
 import os
 import re
 import tempfile

lib/ansible/modules/script.py

@@ -11,12 +11,12 @@ module: script
 version_added: "0.9"
 short_description: Runs a local script on a remote node after transferring it
 description:
-     - The C(script) module takes the script name followed by a list of space-delimited arguments.
-     - Either a free form command or C(cmd) parameter is required, see the examples.
-     - The local script at path will be transferred to the remote node and then executed.
-     - The given script will be processed through the shell environment on the remote node.
-     - This module does not require python on the remote system, much like the M(ansible.builtin.raw) module.
-     - This module is also supported for Windows targets.
+  - The C(script) module takes the script name followed by a list of space-delimited arguments.
+  - Either a free form command or C(cmd) parameter is required, see the examples.
+  - The local script at path will be transferred to the remote node and then executed.
+  - The given script will be processed through the shell environment on the remote node.
+  - This module does not require python on the remote system, much like the M(ansible.builtin.raw) module.
+  - This module is also supported for Windows targets.
 options:
   free_form:
     description:
@@ -47,41 +47,42 @@ notes:
     stderr is sent to stdout. If you depend on separated stdout and stderr result keys, please switch to a copy+command set of tasks instead of using script.
   - If the path to the local script contains spaces, it needs to be quoted.
   - This module is also supported for Windows targets.
+  - Does not support C(check_mode).
 seealso:
-- module: ansible.builtin.shell
-- module: ansible.windows.win_shell
+  - module: ansible.builtin.shell
+  - module: ansible.windows.win_shell
 author:
-    - Ansible Core Team
-    - Michael DeHaan
+  - Ansible Core Team
+  - Michael DeHaan
 extends_documentation_fragment:
-    - decrypt
+  - decrypt
 '''
 
 EXAMPLES = r'''
 - name: Run a script with arguments (free form)
-  script: /some/local/script.sh --some-argument 1234
+  ansible.builtin.script: /some/local/script.sh --some-argument 1234
 
 - name: Run a script with arguments (using 'cmd' parameter)
-  script:
+  ansible.builtin.script:
     cmd: /some/local/script.sh --some-argument 1234
 
 - name: Run a script only if file.txt does not exist on the remote node
-  script: /some/local/create_file.sh --some-argument 1234
+  ansible.builtin.script: /some/local/create_file.sh --some-argument 1234
   args:
     creates: /the/created/file.txt
 
 - name: Run a script only if file.txt exists on the remote node
-  script: /some/local/remove_file.sh --some-argument 1234
+  ansible.builtin.script: /some/local/remove_file.sh --some-argument 1234
   args:
     removes: /the/removed/file.txt
 
 - name: Run a script using an executable in a non-system path
-  script: /some/local/script
+  ansible.builtin.script: /some/local/script
   args:
     executable: /some/remote/executable
 
 - name: Run a script using an executable in a system path
-  script: /some/local/script.py
+  ansible.builtin.script: /some/local/script.py
   args:
     executable: python3
 '''

lib/ansible/modules/service.py

@@ -79,8 +79,9 @@ options:
         version_added: 2.2
 notes:
     - For AIX, group subsystem names can be used.
+    - Supports C(check_mode).
 seealso:
-- module: ansible.windows.win_service
+    - module: ansible.windows.win_service
 author:
     - Ansible Core Team
     - Michael DeHaan
@@ -88,43 +89,45 @@ author:
 
 EXAMPLES = r'''
 - name: Start service httpd, if not started
-  service:
+  ansible.builtin.service:
     name: httpd
     state: started
 
 - name: Stop service httpd, if started
-  service:
+  ansible.builtin.service:
     name: httpd
     state: stopped
 
 - name: Restart service httpd, in all cases
-  service:
+  ansible.builtin.service:
     name: httpd
     state: restarted
 
 - name: Reload service httpd, in all cases
-  service:
+  ansible.builtin.service:
     name: httpd
     state: reloaded
 
 - name: Enable service httpd, and not touch the state
-  service:
+  ansible.builtin.service:
     name: httpd
     enabled: yes
 
 - name: Start service foo, based on running process /usr/bin/foo
-  service:
+  ansible.builtin.service:
     name: foo
     pattern: /usr/bin/foo
     state: started
 
 - name: Restart network service for interface eth0
-  service:
+  ansible.builtin.service:
     name: network
     state: restarted
     args: eth0
 '''
 
+RETURN = r'''#'''
+
 import glob
 import json
 import os