From 17566d7a179f6d4d61e25147b76e52176d83de4a Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Fri, 8 Jan 2021 22:19:05 +0300 Subject: [PATCH] Documentation: fix modules doc formatting (#73037) --- lib/ansible/modules/file.py | 34 +++++++++++++++------------- lib/ansible/modules/rpm_key.py | 13 +++++++---- lib/ansible/modules/service_facts.py | 9 ++++---- lib/ansible/modules/stat.py | 34 +++++++++++++++++----------- lib/ansible/modules/subversion.py | 12 ++++++---- lib/ansible/modules/systemd.py | 23 ++++++++++--------- lib/ansible/modules/unarchive.py | 11 +++++---- 7 files changed, 78 insertions(+), 58 deletions(-) diff --git a/lib/ansible/modules/file.py b/lib/ansible/modules/file.py index 76a3e130c58..f55f6a37934 100644 --- a/lib/ansible/modules/file.py +++ b/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 diff --git a/lib/ansible/modules/rpm_key.py b/lib/ansible/modules/rpm_key.py index 350cf4e3d17..c24d1ce1b00 100644 --- a/lib/ansible/modules/rpm_key.py +++ b/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 diff --git a/lib/ansible/modules/service_facts.py b/lib/ansible/modules/service_facts.py index 407be92128b..91de089cd57 100644 --- a/lib/ansible/modules/service_facts.py +++ b/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''' diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py index 2a5fbcde1f7..717a8ac2ddc 100644 --- a/lib/ansible/modules/stat.py +++ b/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: diff --git a/lib/ansible/modules/subversion.py b/lib/ansible/modules/subversion.py index 730d26f0571..4a5e1dae8e7 100644 --- a/lib/ansible/modules/subversion.py +++ b/lib/ansible/modules/subversion.py @@ -18,8 +18,8 @@ version_added: "0.7" author: - Dane Summers (@dsummersl) 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 diff --git a/lib/ansible/modules/systemd.py b/lib/ansible/modules/systemd.py index a0bf8057c6e..aed276c25a5 100644 --- a/lib/ansible/modules/systemd.py +++ b/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: { diff --git a/lib/ansible/modules/unarchive.py b/lib/ansible/modules/unarchive.py index 749d0288896..d35a77867a4 100644 --- a/lib/ansible/modules/unarchive.py +++ b/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: