Documentation: fix modules doc formatting (#72898)

lib/ansible/modules/file.py

@@ -111,6 +111,8 @@ seealso:
 - module: ansible.builtin.stat
 - module: ansible.builtin.template
 - module: ansible.windows.win_file
+notes:
+- Supports C(check_mode).
 author:
 - Ansible Core Team
 - Michael DeHaan
@@ -118,21 +120,21 @@ author:
 
 EXAMPLES = r'''
 - name: Change file ownership, group and permissions
-  file:
+  ansible.builtin.file:
     path: /etc/foo.conf
     owner: foo
     group: foo
     mode: '0644'
 
 - name: Give insecure permissions to an existing file
-  file:
+  ansible.builtin.file:
     path: /work
     owner: root
     group: root
     mode: '1777'
 
 - name: Create a symbolic link
-  file:
+  ansible.builtin.file:
     src: /file/to/link/to
     dest: /path/to/symlink
     owner: foo
@@ -140,7 +142,7 @@ EXAMPLES = r'''
     state: link
 
 - name: Create two hard links
-  file:
+  ansible.builtin.file:
     src: '/tmp/{{ item.src }}'
     dest: '{{ item.dest }}'
     state: hard
@@ -149,19 +151,19 @@ EXAMPLES = r'''
     - { src: z, dest: k }
 
 - name: Touch a file, using symbolic modes to set the permissions (equivalent to 0644)
-  file:
+  ansible.builtin.file:
     path: /etc/foo.conf
     state: touch
     mode: u=rw,g=r,o=r
 
 - name: Touch the same file, but add/remove some permissions
-  file:
+  ansible.builtin.file:
     path: /etc/foo.conf
     state: touch
     mode: u+rw,g-wx,o-rwx
 
-- name: Touch again the same file, but dont change times this makes the task idempotent
+- name: Touch again the same file, but do not change times this makes the task idempotent
-  file:
+  ansible.builtin.file:
     path: /etc/foo.conf
     state: touch
     mode: u+rw,g-wx,o-rwx
@@ -169,26 +171,26 @@ EXAMPLES = r'''
     access_time: preserve
 
 - name: Create a directory if it does not exist
-  file:
+  ansible.builtin.file:
     path: /etc/some_directory
     state: directory
     mode: '0755'
 
 - name: Update modification and access time of given file
-  file:
+  ansible.builtin.file:
     path: /etc/some_file
     state: file
     modification_time: now
     access_time: now
 
 - name: Set access time based on seconds from epoch value
-  file:
+  ansible.builtin.file:
     path: /etc/another_file
     state: file
     access_time: '{{ "%Y%m%d%H%M.%S" | strftime(stat_var.stat.atime) }}'
 
 - name: Recursively change ownership of a directory
-  file:
+  ansible.builtin.file:
     path: /etc/foo
     state: directory
     recurse: yes
@@ -196,24 +198,24 @@ EXAMPLES = r'''
     group: foo
 
 - name: Remove file (delete file)
-  file:
+  ansible.builtin.file:
     path: /etc/foo.txt
     state: absent
 
 - name: Recursively remove directory
-  file:
+  ansible.builtin.file:
     path: /etc/foo
     state: absent
 
 '''
 RETURN = r'''
 dest:
-    description: Destination file/path, equal to the value passed to I(path)
+    description: Destination file/path, equal to the value passed to I(path).
     returned: state=touch, state=hard, state=link
     type: str
     sample: /path/to/file.txt
 path:
-    description: Destination file/path, equal to the value passed to I(path)
+    description: Destination file/path, equal to the value passed to I(path).
     returned: state=absent, state=directory, state=file
     type: str
     sample: /path/to/file.txt

lib/ansible/modules/rpm_key.py

@@ -44,29 +44,34 @@ options:
         - This will be used to verify the specified key.
       type: str
       version_added: 2.9
+notes:
+  - Supports C(check_mode).
 '''
 
 EXAMPLES = '''
 - name: Import a key from a url
-  rpm_key:
+  ansible.builtin.rpm_key:
     state: present
     key: http://apt.sw.be/RPM-GPG-KEY.dag.txt
 
 - name: Import a key from a file
-  rpm_key:
+  ansible.builtin.rpm_key:
     state: present
     key: /path/to/key.gpg
 
 - name: Ensure a key is not present in the db
-  rpm_key:
+  ansible.builtin.rpm_key:
     state: absent
     key: DEADB33F
 
 - name: Verify the key, using a fingerprint, before import
-  rpm_key:
+  ansible.builtin.rpm_key:
     key: /path/to/RPM-GPG-KEY.dag.txt
     fingerprint: EBC6 E12C 62B1 C734 026B  2122 A20E 5214 6B8D 79E6
 '''
+
+RETURN = r'''#'''
+
 import re
 import os.path
 import tempfile

lib/ansible/modules/service_facts.py

@@ -14,7 +14,7 @@ DOCUMENTATION = r'''
 module: service_facts
 short_description: Return service state information as fact data
 description:
-     - Return service state information as fact data for various service management utilities
+     - Return service state information as fact data for various service management utilities.
 version_added: "2.5"
 requirements: ["Any of the following supported init systems: systemd, sysv, upstart, AIX SRC"]
 
@@ -26,6 +26,7 @@ notes:
     using the string value of the service name as the key in order to obtain
     the fact data value like C(ansible_facts.services['zuul-gateway'])
   - AIX SRC was added in version 2.11.
+  - Supports C(check_mode).
 
 author:
   - Adam Miller (@maxamillion)
@@ -33,11 +34,11 @@ author:
 
 EXAMPLES = r'''
 - name: Populate service facts
-  service_facts:
+  ansible.builtin.service_facts:
 
-- debug:
+- name: Print service facts
+  ansible.builtin.debug:
     var: ansible_facts.services
-
 '''
 
 RETURN = r'''

lib/ansible/modules/stat.py

@@ -64,6 +64,8 @@ options:
 seealso:
 - module: ansible.builtin.file
 - module: ansible.windows.win_stat
+notes:
+- Supports C(check_mode).
 author: Bruce Pennypacker (@bpennypacker)
 '''
 
@@ -71,10 +73,11 @@ EXAMPLES = r'''
 # Obtain the stats of /etc/foo.conf, and check that the file still belongs
 # to 'root'. Fail otherwise.
 - name: Get stats of a file
-  stat:
+  ansible.builtin.stat:
     path: /etc/foo.conf
   register: st
-- fail:
+- name: Fail if the file does not belong to 'root'
+  ansible.builtin.fail:
     msg: "Whoops! file ownership has changed"
   when: st.stat.pw_name != 'root'
 
@@ -84,23 +87,27 @@ EXAMPLES = r'''
 # Run this to understand the structure, the skipped ones do not pass the
 # check performed by 'when'
 - name: Get stats of the FS object
-  stat:
+  ansible.builtin.stat:
     path: /path/to/something
   register: sym
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "islnk isn't defined (path doesn't exist)"
   when: sym.stat.islnk is not defined
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "islnk is defined (path must exist)"
   when: sym.stat.islnk is defined
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "Path exists and is a symlink"
   when: sym.stat.islnk is defined and sym.stat.islnk
 
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "Path exists and isn't a symlink"
   when: sym.stat.islnk is defined and sym.stat.islnk == False
 
@@ -108,27 +115,28 @@ EXAMPLES = r'''
 # Determine if a path exists and is a directory.  Note that we need to test
 # both that p.stat.isdir actually exists, and also that it's set to true.
 - name: Get stats of the FS object
-  stat:
+  ansible.builtin.stat:
     path: /path/to/something
   register: p
-- debug:
+- name: Print a debug message
+  ansible.builtin.debug:
     msg: "Path exists and is a directory"
   when: p.stat.isdir is defined and p.stat.isdir
 
-- name: Don't do checksum
+- name: Don not do checksum
-  stat:
+  ansible.builtin.stat:
     path: /path/to/myhugefile
     get_checksum: no
 
 - name: Use sha256 to calculate checksum
-  stat:
+  ansible.builtin.stat:
     path: /path/to/something
     checksum_algorithm: sha256
 '''
 
 RETURN = r'''
 stat:
-    description: dictionary containing all the stat data, some platforms might add additional fields
+    description: Dictionary containing all the stat data, some platforms might add additional fields.
     returned: success
     type: complex
     contains:

lib/ansible/modules/subversion.py

@@ -18,8 +18,8 @@ version_added: "0.7"
 author:
 - Dane Summers (@dsummersl) <njharman@gmail.com>
 notes:
-   - Requires I(svn) to be installed on the client.
    - This module does not handle externals.
+   - Supports C(check_mode).
 options:
   repo:
     description:
@@ -47,7 +47,7 @@ options:
   in_place:
     description:
       - If the directory exists, then the working copy will be checked-out over-the-top using
-        svn checkout --force; if force is specified then existing files with different content are reverted
+        svn checkout --force; if force is specified then existing files with different content are reverted.
     type: bool
     default: "no"
     version_added: "2.6"
@@ -105,24 +105,26 @@ requirements:
 
 EXAMPLES = '''
 - name: Checkout subversion repository to specified folder
-  subversion:
+  ansible.builtin.subversion:
     repo: svn+ssh://an.example.org/path/to/repo
     dest: /src/checkout
 
 - name: Export subversion directory to folder
-  subversion:
+  ansible.builtin.subversion:
     repo: svn+ssh://an.example.org/path/to/repo
     dest: /src/export
     export: yes
 
 - name: Get information about the repository whether or not it has already been cloned locally
-- subversion:
+  ansible.builtin.subversion:
     repo: svn+ssh://an.example.org/path/to/repo
     dest: /src/checkout
     checkout: no
     update: no
 '''
 
+RETURN = r'''#'''
+
 import os
 import re
 

lib/ansible/modules/systemd.py

@@ -58,8 +58,8 @@ options:
         version_added: "2.8"
     scope:
         description:
-            - run systemctl within a given service manager scope, either as the default system scope (system),
+            - Run systemctl within a given service manager scope, either as the default system scope C(system),
-              the current user's scope (user), or the scope of all users (global).
+              the current user's scope C(user), or the scope of all users C(global).
             - "For systemd to work with 'user', the executing user must have its own instance of dbus started and accessible (systemd requirement)."
             - "The user dbus process is normally started during normal login, but not during the run of Ansible tasks.
               Otherwise you will probably get a 'Failed to connect to bus: no such file or directory' error."
@@ -81,54 +81,55 @@ notes:
       and all except 'daemon_reload' (and 'daemon_reexec' since 2.8) also require 'name'.
     - Before 2.4 you always required 'name'.
     - Globs are not supported in name, i.e ``postgres*.service``.
+    - Supports C(check_mode).
 requirements:
     - A system managed by systemd.
 '''
 
 EXAMPLES = '''
 - name: Make sure a service is running
-  systemd:
+  ansible.builtin.systemd:
     state: started
     name: httpd
 
 - name: Stop service cron on debian, if running
-  systemd:
+  ansible.builtin.systemd:
     name: cron
     state: stopped
 
 - name: Restart service cron on centos, in all cases, also issue daemon-reload to pick up config changes
-  systemd:
+  ansible.builtin.systemd:
     state: restarted
     daemon_reload: yes
     name: crond
 
 - name: Reload service httpd, in all cases
-  systemd:
+  ansible.builtin.systemd:
     name: httpd
     state: reloaded
 
 - name: Enable service httpd and ensure it is not masked
-  systemd:
+  ansible.builtin.systemd:
     name: httpd
     enabled: yes
     masked: no
 
 - name: Enable a timer for dnf-automatic
-  systemd:
+  ansible.builtin.systemd:
     name: dnf-automatic.timer
     state: started
     enabled: yes
 
 - name: Just force systemd to reread configs (2.4 and above)
-  systemd:
+  ansible.builtin.systemd:
     daemon_reload: yes
 
 - name: Just force systemd to re-execute itself (2.8 and above)
-  systemd:
+  ansible.builtin.systemd:
     daemon_reexec: yes
 
-- name: run a user service when XDG_RUNTIME_DIR is not set on remote login.
+- name: Run a user service when XDG_RUNTIME_DIR is not set on remote login
-  systemd:
+  ansible.builtin.systemd:
     name: myservice
     state: started
     scope: user
@@ -138,7 +139,7 @@ EXAMPLES = '''
 
 RETURN = '''
 status:
-    description: A dictionary with the key=value pairs returned from `systemctl show`
+    description: A dictionary with the key=value pairs returned from `systemctl show`.
     returned: success
     type: complex
     sample: {

lib/ansible/modules/unarchive.py

@@ -16,7 +16,7 @@ DOCUMENTATION = r'''
 ---
 module: unarchive
 version_added: '1.4'
-short_description: Unpacks an archive after (optionally) copying it from the local machine.
+short_description: Unpacks an archive after (optionally) copying it from the local machine
 description:
      - The C(unarchive) module unpacks an archive. It will not unpack a compressed file that does not contain an archive.
      - By default, it will copy the source file from the local system to the target before unpacking.
@@ -118,6 +118,7 @@ notes:
       are not touched. This is the same behavior as a normal archive extraction.
     - Existing files/directories in the destination which are not in the archive
       are ignored for purposes of deciding if the archive should be unpacked or not.
+    - Supports C(check_mode).
 seealso:
 - module: community.general.archive
 - module: community.general.iso_extract
@@ -127,24 +128,24 @@ author: Michael DeHaan
 
 EXAMPLES = r'''
 - name: Extract foo.tgz into /var/lib/foo
-  unarchive:
+  ansible.builtin.unarchive:
     src: foo.tgz
     dest: /var/lib/foo
 
 - name: Unarchive a file that is already on the remote machine
-  unarchive:
+  ansible.builtin.unarchive:
     src: /tmp/foo.zip
     dest: /usr/local/bin
     remote_src: yes
 
 - name: Unarchive a file that needs to be downloaded (added in 2.0)
-  unarchive:
+  ansible.builtin.unarchive:
     src: https://example.com/example.zip
     dest: /usr/local/bin
     remote_src: yes
 
 - name: Unarchive a file with extra options
-  unarchive:
+  ansible.builtin.unarchive:
     src: /tmp/foo.zip
     dest: /usr/local/bin
     extra_opts: