From 6cde1cdf35fd20ef299f0afceb371dcf8019bca1 Mon Sep 17 00:00:00 2001 From: Andrew Klychkov Date: Wed, 3 Feb 2021 19:18:41 +0300 Subject: [PATCH] Documentation: fix formatting (#73186) --- lib/ansible/modules/command.py | 41 +++++++-------- lib/ansible/modules/debug.py | 2 +- lib/ansible/modules/expect.py | 10 ++-- lib/ansible/modules/git.py | 49 +++++++++--------- lib/ansible/modules/group.py | 2 +- lib/ansible/modules/group_by.py | 10 ++-- lib/ansible/modules/hostname.py | 2 +- lib/ansible/modules/package.py | 9 ++-- lib/ansible/modules/package_facts.py | 14 ++--- lib/ansible/modules/user.py | 77 ++++++++++++++-------------- 10 files changed, 110 insertions(+), 106 deletions(-) diff --git a/lib/ansible/modules/command.py b/lib/ansible/modules/command.py index dcecbe646fa..1680543295a 100644 --- a/lib/ansible/modules/command.py +++ b/lib/ansible/modules/command.py @@ -45,7 +45,7 @@ options: creates: type: path description: - - A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(won't) be run. + - A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(will not) be run. removes: type: path description: @@ -79,11 +79,12 @@ options: type: bool default: yes notes: - - If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(ansible.builtin.shell) module instead. + - If you want to run a command through the shell (say you are using C(<), C(>), C(|), and so on), + you actually want the M(ansible.builtin.shell) module instead. Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to use the C(command) module when possible. - - " C(creates), C(removes), and C(chdir) can be specified after the command. - For instance, if you only want to run a command if a certain file does not exist, use this." + - C(creates), C(removes), and C(chdir) can be specified after the command. + For instance, if you only want to run a command if a certain file does not exist, use this. - Check mode is supported when passing C(creates) or C(removes). If running in check mode and either of these are specified, the module will check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped. - The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead. @@ -101,28 +102,28 @@ author: EXAMPLES = r''' - name: Return motd to registered var - command: cat /etc/motd + ansible.builtin.command: cat /etc/motd register: mymotd # free-form (string) arguments, all arguments on one line - name: Run command if /path/to/database does not exist (without 'args') - command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database + ansible.builtin.command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database # free-form (string) arguments, some arguments on separate lines with the 'args' keyword # 'args' is a task keyword, passed at the same level as the module - name: Run command if /path/to/database does not exist (with 'args' keyword) - command: /usr/bin/make_database.sh db_user db_name + ansible.builtin.command: /usr/bin/make_database.sh db_user db_name args: creates: /path/to/database # 'cmd' is module parameter - name: Run command if /path/to/database does not exist (with 'cmd' parameter) - command: + ansible.builtin.command: cmd: /usr/bin/make_database.sh db_user db_name creates: /path/to/database - name: Change the working directory to somedir/ and run the command as db_owner if /path/to/database does not exist - command: /usr/bin/make_database.sh db_user db_name + ansible.builtin.command: /usr/bin/make_database.sh db_user db_name become: yes become_user: db_owner args: @@ -132,7 +133,7 @@ EXAMPLES = r''' # argv (list) arguments, each argument on a separate line, 'args' keyword not necessary # 'argv' is a parameter, indented one level from the module - name: Use 'argv' to send a command as a list - leave 'command' empty - command: + ansible.builtin.command: argv: - /usr/bin/make_database.sh - Username with whitespace @@ -140,7 +141,7 @@ EXAMPLES = r''' creates: /path/to/database - name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues - command: cat {{ myfile|quote }} + ansible.builtin.command: cat {{ myfile|quote }} register: myoutput ''' @@ -151,49 +152,49 @@ msg: type: bool sample: True start: - description: The command execution start time + description: The command execution start time. returned: always type: str sample: '2017-09-29 22:03:48.083128' end: - description: The command execution end time + description: The command execution end time. returned: always type: str sample: '2017-09-29 22:03:48.084657' delta: - description: The command execution delta time + description: The command execution delta time. returned: always type: str sample: '0:00:00.001529' stdout: - description: The command standard output + description: The command standard output. returned: always type: str sample: 'Clustering node rabbit@slave1 with rabbit@master …' stderr: - description: The command standard error + description: The command standard error. returned: always type: str sample: 'ls cannot access foo: No such file or directory' cmd: - description: The command executed by the task + description: The command executed by the task. returned: always type: list sample: - echo - hello rc: - description: The command return code (0 means success) + description: The command return code (0 means success). returned: always type: int sample: 0 stdout_lines: - description: The command standard output split in lines + description: The command standard output split in lines. returned: always type: list sample: [u'Clustering node rabbit@slave1 with rabbit@master …'] stderr_lines: - description: The command standard error split in lines + description: The command standard error split in lines. returned: always type: list sample: [u'ls cannot access foo: No such file or directory', u'ls …'] diff --git a/lib/ansible/modules/debug.py b/lib/ansible/modules/debug.py index 86c4b951749..c98bcc57022 100644 --- a/lib/ansible/modules/debug.py +++ b/lib/ansible/modules/debug.py @@ -34,7 +34,7 @@ options: type: str verbosity: description: - - A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above + - A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above. type: int default: 0 version_added: '2.1' diff --git a/lib/ansible/modules/expect.py b/lib/ansible/modules/expect.py index 0f2621566f2..3bb9d9608ef 100644 --- a/lib/ansible/modules/expect.py +++ b/lib/ansible/modules/expect.py @@ -12,7 +12,7 @@ DOCUMENTATION = r''' --- module: expect version_added: '2.0' -short_description: Executes a command and responds to prompts. +short_description: Executes a command and responds to prompts description: - The C(expect) module executes a command and responds to prompts. - The given command will be executed on all selected nodes. It will not be @@ -58,7 +58,7 @@ requirements: - pexpect >= 3.3 notes: - If you want to run a command through the shell (say you are using C(<), - C(>), C(|), etc), you must specify a shell in the command such as + C(>), C(|), and so on), you must specify a shell in the command such as C(/bin/bash -c "/path/to/something | grep else"). - The question, or key, under I(responses) is a python regex match. Case insensitive searches are indicated with a prefix of C(?i). @@ -68,7 +68,7 @@ notes: the response. The list functionality is new in 2.1. - The M(ansible.builtin.expect) module is designed for simple scenarios. For more complex needs, consider the use of expect code with the M(ansible.builtin.shell) - or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation) + or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation). seealso: - module: ansible.builtin.script - module: ansible.builtin.shell @@ -77,7 +77,7 @@ author: "Matt Martz (@sivel)" EXAMPLES = r''' - name: Case insensitive password string match - expect: + ansible.builtin.expect: command: passwd username responses: (?i)password: "MySekretPa$$word" @@ -85,7 +85,7 @@ EXAMPLES = r''' no_log: true - name: Generic question with multiple different responses - expect: + ansible.builtin.expect: command: /path/to/custom/command responses: Question: diff --git a/lib/ansible/modules/git.py b/lib/ansible/modules/git.py index b47e94517bd..8f432fd07cb 100644 --- a/lib/ansible/modules/git.py +++ b/lib/ansible/modules/git.py @@ -33,12 +33,12 @@ options: description: - What version of the repository to check out. This can be the literal string C(HEAD), a branch name, a tag name. - It can also be a I(SHA-1) hash, in which case C(refspec) needs + It can also be a I(SHA-1) hash, in which case I(refspec) needs to be specified if the given revision is not already available. default: "HEAD" accept_hostkey: description: - - if C(yes), ensure that "-o StrictHostKeyChecking=no" is + - If C(yes), ensure that "-o StrictHostKeyChecking=no" is present as an ssh option. type: bool default: 'no' @@ -57,7 +57,7 @@ options: version_added: "1.5" reference: description: - - Reference repository (see "git clone --reference ...") + - Reference repository (see "git clone --reference ..."). version_added: "1.4" remote: description: @@ -77,7 +77,7 @@ options: - If C(yes), any modified files in the working repository will be discarded. Prior to 0.7, this was always 'yes' and could not be disabled. Prior to 1.9, the default was - `yes` + `yes`. type: bool default: 'no' version_added: "0.7" @@ -89,13 +89,13 @@ options: version_added: "1.2" clone: description: - - If C(no), do not clone the repository even if it does not exist locally + - If C(no), do not clone the repository even if it does not exist locally. type: bool default: 'yes' version_added: "1.9" update: description: - - If C(no), do not retrieve new revisions from the origin repository + - If C(no), do not retrieve new revisions from the origin repository. - Operations like archive will work on the existing (old) repository and might not respond to changes to the options version or remote. type: bool @@ -108,7 +108,7 @@ options: version_added: "1.4" bare: description: - - if C(yes), repository will be created as a bare repo, otherwise + - If C(yes), repository will be created as a bare repo, otherwise it will be a standard repo with a workspace. type: bool default: 'no' @@ -121,7 +121,7 @@ options: recursive: description: - - if C(no), repository will be cloned without the --recursive + - If C(no), repository will be cloned without the --recursive option, skipping sub-modules. type: bool default: 'yes' @@ -129,7 +129,7 @@ options: track_submodules: description: - - if C(yes), submodules will track the latest commit on their + - If C(yes), submodules will track the latest commit on their master branch (or other branch specified in .gitmodules). If C(no), submodules will be kept at the revision specified by the main project. This is equivalent to specifying the --remote flag @@ -140,8 +140,8 @@ options: verify_commit: description: - - if C(yes), when cloning or checking out a C(version) verify the - signature of a GPG signed commit. This requires C(git) version>=2.1.0 + - If C(yes), when cloning or checking out a I(version) verify the + signature of a GPG signed commit. This requires git version>=2.1.0 to be installed. The commit MUST be signed and the public key MUST be present in the GPG keyring. type: bool @@ -153,14 +153,14 @@ options: - Specify archive file path with extension. If specified, creates an archive file of the specified format containing the tree structure for the source tree. - Allowed archive formats ["zip", "tar.gz", "tar", "tgz"] + Allowed archive formats ["zip", "tar.gz", "tar", "tgz"]. - This will clone and perform git archive from local directory as not all git servers support git archive. version_added: "2.4" archive_prefix: description: - - Specify a prefix to add to each file path in archive. Requires C(archive) to be specified. + - Specify a prefix to add to each file path in archive. Requires I(archive) to be specified. version_added: "2.10" type: str @@ -188,47 +188,48 @@ notes: one solution is to use the option accept_hostkey. Another solution is to add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts." + - Supports C(check_mode). ''' EXAMPLES = ''' - name: Git checkout - git: + ansible.builtin.git: repo: 'https://foosball.example.org/path/to/repo.git' dest: /srv/checkout version: release-0.22 - name: Read-write git checkout from github - git: + ansible.builtin.git: repo: git@github.com:mylogin/hello.git dest: /home/mylogin/hello - name: Just ensuring the repo checkout exists - git: + ansible.builtin.git: repo: 'https://foosball.example.org/path/to/repo.git' dest: /srv/checkout update: no - name: Just get information about the repository whether or not it has already been cloned locally - git: + ansible.builtin.git: repo: 'https://foosball.example.org/path/to/repo.git' dest: /srv/checkout clone: no update: no - name: Checkout a github repo and use refspec to fetch all pull requests - git: + ansible.builtin.git: repo: https://github.com/ansible/ansible-examples.git dest: /src/ansible-examples refspec: '+refs/pull/*:refs/heads/*' - name: Create git archive from repo - git: + ansible.builtin.git: repo: https://github.com/ansible/ansible-examples.git dest: /src/ansible-examples archive: /tmp/ansible-examples.zip - name: Clone a repo with separate git directory - git: + ansible.builtin.git: repo: https://github.com/ansible/ansible-examples.git dest: /src/ansible-examples separate_git_dir: /src/ansible-examples.git @@ -236,12 +237,12 @@ EXAMPLES = ''' RETURN = ''' after: - description: last commit revision of the repository retrieved during the update + description: Last commit revision of the repository retrieved during the update. returned: success type: str sample: 4c020102a9cd6fe908c9a4a326a38f972f63a903 before: - description: commit revision before the repository was updated, "null" for new repository + description: Commit revision before the repository was updated, "null" for new repository. returned: success type: str sample: 67c04ebe40a003bda0efb34eacfb93b0cafdf628 @@ -256,12 +257,12 @@ warnings: type: str sample: Your git version is too old to fully support the depth argument. Falling back to full checkouts. git_dir_now: - description: Contains the new path of .git directory if it's changed + description: Contains the new path of .git directory if it is changed. returned: success type: str sample: /path/to/new/git/dir git_dir_before: - description: Contains the original path of .git directory if it's changed + description: Contains the original path of .git directory if it is changed. returned: success type: str sample: /path/to/old/git/dir diff --git a/lib/ansible/modules/group.py b/lib/ansible/modules/group.py index 1deb967afe3..297e25796d6 100644 --- a/lib/ansible/modules/group.py +++ b/lib/ansible/modules/group.py @@ -45,7 +45,7 @@ options: description: - Forces the use of "local" command alternatives on platforms that implement it. - This is useful in environments that use centralized authentication when you want to manipulate the local groups. - (e.g. it uses C(lgroupadd) instead of C(groupadd)). + (for example, it uses C(lgroupadd) instead of C(groupadd)). - This requires that these commands exist on the targeted host, otherwise it will be a fatal error. type: bool default: no diff --git a/lib/ansible/modules/group_by.py b/lib/ansible/modules/group_by.py index 4a709d287ea..34290d02b72 100644 --- a/lib/ansible/modules/group_by.py +++ b/lib/ansible/modules/group_by.py @@ -39,20 +39,20 @@ author: EXAMPLES = r''' - name: Create groups based on the machine architecture - group_by: + ansible.builtin.group_by: key: machine_{{ ansible_machine }} - name: Create groups like 'virt_kvm_host' - group_by: + ansible.builtin.group_by: key: virt_{{ ansible_virtualization_type }}_{{ ansible_virtualization_role }} - name: Create nested groups - group_by: + ansible.builtin.group_by: key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }} parents: - el{{ ansible_distribution_major_version }} -# Add all active hosts to a static group -- group_by: +- name: Add all active hosts to a static group + ansible.builtin.group_by: key: done ''' diff --git a/lib/ansible/modules/hostname.py b/lib/ansible/modules/hostname.py index c0ffe37adfb..ab99045a585 100644 --- a/lib/ansible/modules/hostname.py +++ b/lib/ansible/modules/hostname.py @@ -36,7 +36,7 @@ options: EXAMPLES = ''' - name: Set a hostname - hostname: + ansible.builtin.hostname: name: web01 ''' diff --git a/lib/ansible/modules/package.py b/lib/ansible/modules/package.py index a99dab1d6be..f15ad5af8ed 100644 --- a/lib/ansible/modules/package.py +++ b/lib/ansible/modules/package.py @@ -33,9 +33,8 @@ options: required: true use: description: - - The required package manager module to use (yum, apt, etc). The default 'auto' will use existing facts or try to autodetect it. + - The required package manager module to use (`yum`, `apt`, and so on). The default 'auto' will use existing facts or try to autodetect it. - You should only use this field if the automatic selection is not working for some reason. - required: false default: auto requirements: - Whatever is required for the package plugins specific for each system. @@ -45,18 +44,18 @@ notes: ''' EXAMPLES = ''' - name: Install ntpdate - package: + ansible.builtin.package: name: ntpdate state: present # This uses a variable as this changes per distribution. - name: Remove the apache package - package: + ansible.builtin.package: name: "{{ apache }}" state: absent - name: Install the latest version of Apache and MariaDB - package: + ansible.builtin.package: name: - httpd - mariadb-server diff --git a/lib/ansible/modules/package_facts.py b/lib/ansible/modules/package_facts.py index ed314b4a29d..97bfd6f0c1d 100644 --- a/lib/ansible/modules/package_facts.py +++ b/lib/ansible/modules/package_facts.py @@ -10,9 +10,9 @@ __metaclass__ = type DOCUMENTATION = ''' module: package_facts -short_description: package information as facts +short_description: Package information as facts description: - - Return information about installed packages as facts + - Return information about installed packages as facts. options: manager: description: @@ -39,19 +39,21 @@ author: - Matthew Jones (@matburt) - Brian Coca (@bcoca) - Adam Miller (@maxamillion) +notes: + - Supports C(check_mode). ''' EXAMPLES = ''' - name: Gather the package facts - package_facts: + ansible.builtin.package_facts: manager: auto - name: Print the package facts - debug: + ansible.builtin.debug: var: ansible_facts.packages - name: Check whether a package called foobar is installed - debug: + ansible.builtin.debug: msg: "{{ ansible_facts.packages['foobar'] | length }} versions of foobar are installed!" when: "'foobar' in ansible_facts.packages" @@ -59,7 +61,7 @@ EXAMPLES = ''' RETURN = ''' ansible_facts: - description: facts to add to ansible_facts + description: Facts to add to ansible_facts. returned: always type: complex contains: diff --git a/lib/ansible/modules/user.py b/lib/ansible/modules/user.py index 0e37cbf5310..583dfe22fcd 100644 --- a/lib/ansible/modules/user.py +++ b/lib/ansible/modules/user.py @@ -203,7 +203,7 @@ options: description: - Forces the use of "local" command alternatives on platforms that implement it. - This is useful in environments that use centralized authentication when you want to manipulate the local users - (i.e. it uses C(luseradd) instead of C(useradd)). + (in other words, it uses C(luseradd) instead of C(useradd)). - This will check C(/etc/passwd) for an existing account before invoking commands. If the local account database exists somewhere other than C(/etc/passwd), this setting will not work properly. - This requires that the above commands as well as C(/etc/passwd) must exist on the target host, otherwise it will be a fatal error. @@ -250,6 +250,7 @@ notes: C(pw userdel) remove, C(pw lock) to lock, and C(pw unlock) to unlock accounts. - On all other platforms, this module uses C(useradd) to create, C(usermod) to modify, and C(userdel) to remove accounts. + - Supports C(check_mode). seealso: - module: ansible.posix.authorized_key - module: ansible.builtin.group @@ -260,64 +261,64 @@ author: EXAMPLES = r''' - name: Add the user 'johnd' with a specific uid and a primary group of 'admin' - user: + ansible.builtin.user: name: johnd comment: John Doe uid: 1040 group: admin - name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups - user: + ansible.builtin.user: name: james shell: /bin/bash groups: admins,developers append: yes - name: Remove the user 'johnd' - user: + ansible.builtin.user: name: johnd state: absent remove: yes - name: Create a 2048-bit SSH key for user jsmith in ~jsmith/.ssh/id_rsa - user: + ansible.builtin.user: name: jsmith generate_ssh_key: yes ssh_key_bits: 2048 ssh_key_file: .ssh/id_rsa - name: Added a consultant whose account you want to expire - user: + ansible.builtin.user: name: james18 shell: /bin/zsh groups: developers expires: 1422403387 - name: Starting at Ansible 2.6, modify user, remove expiry time - user: + ansible.builtin.user: name: james18 expires: -1 ''' RETURN = r''' append: - description: Whether or not to append the user to groups - returned: When state is 'present' and the user exists + description: Whether or not to append the user to groups. + returned: When state is C(present) and the user exists type: bool sample: True comment: - description: Comment section from passwd file, usually the user name + description: Comment section from passwd file, usually the user name. returned: When user exists type: str sample: Agent Smith create_home: - description: Whether or not to create the home directory + description: Whether or not to create the home directory. returned: When user does not exist and not check mode type: bool sample: True force: - description: Whether or not a user account was forcibly deleted - returned: When state is 'absent' and user exists + description: Whether or not a user account was forcibly deleted. + returned: When I(state) is C(absent) and user exists type: bool sample: False group: @@ -326,76 +327,76 @@ group: type: int sample: 1001 groups: - description: List of groups of which the user is a member - returned: When C(groups) is not empty and C(state) is 'present' + description: List of groups of which the user is a member. + returned: When I(groups) is not empty and I(state) is C(present) type: str sample: 'chrony,apache' home: - description: "Path to user's home directory" - returned: When C(state) is 'present' + description: "Path to user's home directory." + returned: When I(state) is C(present) type: str sample: '/home/asmith' move_home: - description: Whether or not to move an existing home directory - returned: When C(state) is 'present' and user exists + description: Whether or not to move an existing home directory. + returned: When I(state) is C(present) and user exists type: bool sample: False name: - description: User account name + description: User account name. returned: always type: str sample: asmith password: - description: Masked value of the password - returned: When C(state) is 'present' and C(password) is not empty + description: Masked value of the password. + returned: When I(state) is C(present) and I(password) is not empty type: str sample: 'NOT_LOGGING_PASSWORD' remove: - description: Whether or not to remove the user account - returned: When C(state) is 'absent' and user exists + description: Whether or not to remove the user account. + returned: When I(state) is C(absent) and user exists type: bool sample: True shell: - description: User login shell - returned: When C(state) is 'present' + description: User login shell. + returned: When I(state) is C(present) type: str sample: '/bin/bash' ssh_fingerprint: - description: Fingerprint of generated SSH key - returned: When C(generate_ssh_key) is C(True) + description: Fingerprint of generated SSH key. + returned: When I(generate_ssh_key) is C(True) type: str sample: '2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA)' ssh_key_file: - description: Path to generated SSH private key file - returned: When C(generate_ssh_key) is C(True) + description: Path to generated SSH private key file. + returned: When I(generate_ssh_key) is C(True) type: str sample: /home/asmith/.ssh/id_rsa ssh_public_key: - description: Generated SSH public key file - returned: When C(generate_ssh_key) is C(True) + description: Generated SSH public key file. + returned: When I(generate_ssh_key) is C(True) type: str sample: > 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo 618mUJBvdlEgea96QGjOwSB7/gmonduC7gsWDMNcOdSE3wJMTim4lddiBx4RgC9yXsJ6Tkz9BHD73MXPpT5ETnse+A3fw3IGVSjaueVnlUyUmOBf7fzmZbhlFVXf2Zi2rFTXqvbdGHKkzpw1U8eB8xFPP7y d5u1u0e6Acju/8aZ/l17IDFiLke5IzlqIMRTEbDwLNeO84YQKWTm9fODHzhYe0yvxqLiK07 ansible-generated on host' stderr: - description: Standard error from running commands + description: Standard error from running commands. returned: When stderr is returned by a command that is run type: str sample: Group wheels does not exist stdout: - description: Standard output from running commands + description: Standard output from running commands. returned: When standard output is returned by the command that is run type: str sample: system: - description: Whether or not the account is a system account - returned: When C(system) is passed to the module and the account does not exist + description: Whether or not the account is a system account. + returned: When I(system) is passed to the module and the account does not exist type: bool sample: True uid: - description: User ID of the user account - returned: When C(UID) is passed to the module + description: User ID of the user account. + returned: When I(uid) is passed to the module type: int sample: 1044 '''