Documentation: fix modules doc formatting (#73037)

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
-  file:
+- name: Touch again the same file, but do not change times this makes the task idempotent
+  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

@@ -42,29 +42,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"]
 
@@ -25,6 +25,7 @@ notes:
     C(ansible_facts.services.zuul-gateway). It is instead recommended to
     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'])
+  - Supports C(check_mode).
 
 author:
   - Adam Miller (@maxamillion)
@@ -32,11 +33,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
-  stat:
+- name: Don not do checksum
+  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:
@@ -44,7 +44,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"
@@ -92,24 +92,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

@@ -63,8 +63,8 @@ options:
         type: bool
     scope:
         description:
-            - run systemctl within a given service manager scope, either as the default system scope (system),
-              the current user's scope (user), or the scope of all users (global).
+            - Run systemctl within a given service manager scope, either as the default system scope C(system),
+              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 (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."
@@ -83,56 +83,57 @@ 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
 '''
 
 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.
@@ -105,6 +105,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
@@ -114,24 +115,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: