From c1dadfdadc68a6c9f0c3f9f8fe22a34b5290a45c Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Fri, 18 Dec 2020 19:45:07 +0300 Subject: [PATCH] Documentation: fix modules doc formatting (#72898) --- 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 | 27 +++++++++++----------- lib/ansible/modules/unarchive.py | 11 +++++---- 7 files changed, 80 insertions(+), 60 deletions(-) diff --git a/lib/ansible/modules/file.py b/lib/ansible/modules/file.py index 06921a8d607..7e9a6f8257e 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 c5016dd7eaa..46ef34c2466 100644 --- a/lib/ansible/modules/rpm_key.py +++ b/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 diff --git a/lib/ansible/modules/service_facts.py b/lib/ansible/modules/service_facts.py index 81b2496b955..6440e33b3ff 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, 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''' diff --git a/lib/ansible/modules/stat.py b/lib/ansible/modules/stat.py index 42b6fd8b3fd..d474aac3ffd 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 57d2c0b7b38..c28471bf227 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: @@ -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 diff --git a/lib/ansible/modules/systemd.py b/lib/ansible/modules/systemd.py index 1c2485abf22..32a8de390c0 100644 --- a/lib/ansible/modules/systemd.py +++ b/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), - 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 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. - systemd: +- name: Run a user service when XDG_RUNTIME_DIR is not set on remote login + 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: { diff --git a/lib/ansible/modules/unarchive.py b/lib/ansible/modules/unarchive.py index 3adabdc70b1..90d98f0a2e4 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. @@ -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: