Documentation: fix modules doc formatting (#72898)

This commit is contained in:
Andrew Klychkov 2020-12-18 19:45:07 +03:00 committed by GitHub
parent 389c7b7806
commit c1dadfdadc
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 80 additions and 60 deletions

View file

@ -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

View file

@ -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

View file

@ -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'''

View file

@ -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:

View file

@ -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

View file

@ -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: {

View file

@ -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: