Documentation: fix modules doc formatting (#72788)

* Update lib/ansible/modules/apt_key.py

Co-authored-by: Felix Fontein <felix@fontein.de>
Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
pull/72842/head
Andrew Klychkov 4 years ago committed by GitHub
parent 08842cd6bb
commit 10e59ef749
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -25,7 +25,8 @@ notes:
- "Use full fingerprint (40 characters) key ids to avoid key collisions.
To generate a full-fingerprint imported key: C(apt-key adv --list-public-keys --with-fingerprint --with-colons)."
- If you specify both the key id and the URL with C(state=present), the task can verify or add the key as needed.
- Adding a new key requires an apt cache update (e.g. using the apt module's update_cache option)
- Adding a new key requires an apt cache update (e.g. using the M(ansible.builtin.apt) module's update_cache option).
- Supports C(check_mode).
requirements:
- gpg
options:
@ -46,7 +47,7 @@ options:
type: path
keyring:
description:
- The full path to specific keyring file in /etc/apt/trusted.gpg.d/
- The full path to specific keyring file in C(/etc/apt/trusted.gpg.d/).
type: path
version_added: "1.3"
url:
@ -74,45 +75,46 @@ options:
EXAMPLES = '''
- name: Add an apt key by id from a keyserver
apt_key:
ansible.builtin.apt_key:
keyserver: keyserver.ubuntu.com
id: 36A1D7869245C8950F966E92D8576A8BA88D21E9
- name: Add an Apt signing key, uses whichever key is at the URL
apt_key:
ansible.builtin.apt_key:
url: https://ftp-master.debian.org/keys/archive-key-6.0.asc
state: present
- name: Add an Apt signing key, will not download if present
apt_key:
ansible.builtin.apt_key:
id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA
url: https://ftp-master.debian.org/keys/archive-key-6.0.asc
state: present
- name: Remove a Apt specific signing key, leading 0x is valid
apt_key:
ansible.builtin.apt_key:
id: 0x9FED2BCBDCD29CDF762678CBAED4B06F473041FA
state: absent
# Use armored file since utf-8 string is expected. Must be of "PGP PUBLIC KEY BLOCK" type.
- name: Add a key from a file on the Ansible server.
apt_key:
- name: Add a key from a file on the Ansible server
ansible.builtin.apt_key:
data: "{{ lookup('file', 'apt.asc') }}"
state: present
- name: Add an Apt signing key to a specific keyring file
apt_key:
ansible.builtin.apt_key:
id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA
url: https://ftp-master.debian.org/keys/archive-key-6.0.asc
keyring: /etc/apt/trusted.gpg.d/debian.gpg
- name: Add Apt signing key on remote server to keyring
apt_key:
ansible.builtin.apt_key:
id: 9FED2BCBDCD29CDF762678CBAED4B06F473041FA
file: /tmp/apt.gpg
state: present
'''
RETURN = '''#'''
# FIXME: standardize into module_common
from traceback import format_exc

@ -20,6 +20,7 @@ description:
notes:
- This module works on Debian, Ubuntu and their derivatives.
- This module supports Debian Squeeze (version 6) as well as its successors.
- Supports C(check_mode).
options:
repo:
description:
@ -73,7 +74,8 @@ options:
codename:
description:
- Override the distribution codename to use for PPA repositories.
Should usually only be set when working with a PPA on a non-Ubuntu target (e.g. Debian or Mint)
Should usually only be set when working with a PPA on
a non-Ubuntu target (for example, Debian or Mint).
type: str
version_added: '2.3'
author:
@ -86,36 +88,38 @@ requirements:
EXAMPLES = '''
- name: Add specified repository into sources list
apt_repository:
ansible.builtin.apt_repository:
repo: deb http://archive.canonical.com/ubuntu hardy partner
state: present
- name: Add specified repository into sources list using specified filename
apt_repository:
ansible.builtin.apt_repository:
repo: deb http://dl.google.com/linux/chrome/deb/ stable main
state: present
filename: google-chrome
- name: Add source repository into sources list
apt_repository:
ansible.builtin.apt_repository:
repo: deb-src http://archive.canonical.com/ubuntu hardy partner
state: present
- name: Remove specified repository from sources list
apt_repository:
ansible.builtin.apt_repository:
repo: deb http://archive.canonical.com/ubuntu hardy partner
state: absent
- name: Add nginx stable repository from PPA and install its signing key on Ubuntu target
apt_repository:
ansible.builtin.apt_repository:
repo: ppa:nginx/stable
- name: Add nginx stable repository from PPA and install its signing key on Debian target
apt_repository:
ansible.builtin.apt_repository:
repo: 'ppa:nginx/stable'
codename: trusty
'''
RETURN = '''#'''
import glob
import json
import os

@ -87,23 +87,25 @@ extends_documentation_fragment:
EXAMPLES = r'''
- name: Assemble from fragments from a directory
assemble:
ansible.builtin.assemble:
src: /etc/someapp/fragments
dest: /etc/someapp/someapp.conf
- name: Insert the provided delimiter between fragments
assemble:
ansible.builtin.assemble:
src: /etc/someapp/fragments
dest: /etc/someapp/someapp.conf
delimiter: '### START FRAGMENT ###'
- name: Assemble a new "sshd_config" file into place, after passing validation with sshd
assemble:
ansible.builtin.assemble:
src: /etc/ssh/conf.d/
dest: /etc/ssh/sshd_config
validate: /usr/sbin/sshd -t -f %s
'''
RETURN = r'''#'''
import codecs
import os
import re

@ -118,6 +118,7 @@ extends_documentation_fragment:
- validate
notes:
- The M(ansible.builtin.copy) module recursively copy facility does not scale to lots (>hundreds) of files.
- Supports C(check_mode).
seealso:
- module: ansible.builtin.assemble
- module: ansible.builtin.fetch
@ -132,7 +133,7 @@ author:
EXAMPLES = r'''
- name: Copy file with owner and permissions
copy:
ansible.builtin.copy:
src: /srv/myfiles/foo.conf
dest: /etc/foo.conf
owner: foo
@ -140,7 +141,7 @@ EXAMPLES = r'''
mode: '0644'
- name: Copy file with owner and permission, using symbolic representation
copy:
ansible.builtin.copy:
src: /srv/myfiles/foo.conf
dest: /etc/foo.conf
owner: foo
@ -148,7 +149,7 @@ EXAMPLES = r'''
mode: u=rw,g=r,o=r
- name: Another symbolic mode example, adding some permissions and removing others
copy:
ansible.builtin.copy:
src: /srv/myfiles/foo.conf
dest: /etc/foo.conf
owner: foo
@ -156,7 +157,7 @@ EXAMPLES = r'''
mode: u+rw,g-wx,o-rwx
- name: Copy a new "ntp.conf" file into place, backing up the original if it differs from the copied version
copy:
ansible.builtin.copy:
src: /mine/ntp.conf
dest: /etc/ntp.conf
owner: root
@ -165,31 +166,31 @@ EXAMPLES = r'''
backup: yes
- name: Copy a new "sudoers" file into place, after passing validation with visudo
copy:
ansible.builtin.copy:
src: /mine/sudoers
dest: /etc/sudoers
validate: /usr/sbin/visudo -csf %s
- name: Copy a "sudoers" file on the remote machine for editing
copy:
ansible.builtin.copy:
src: /etc/sudoers
dest: /etc/sudoers.edit
remote_src: yes
validate: /usr/sbin/visudo -csf %s
- name: Copy using inline content
copy:
ansible.builtin.copy:
content: '# This file was moved to /etc/other.conf'
dest: /etc/mine.conf
- name: If follow=yes, /path/to/file will be overwritten by contents of foo.conf
copy:
ansible.builtin.copy:
src: /etc/foo.conf
dest: /path/to/link # link to /path/to/file
follow: yes
- name: If follow=no, /path/to/link will become a file and be overwritten by contents of foo.conf
copy:
ansible.builtin.copy:
src: /etc/foo.conf
dest: /path/to/link # link to /path/to/file
follow: no
@ -197,62 +198,62 @@ EXAMPLES = r'''
RETURN = r'''
dest:
description: Destination file/path
description: Destination file/path.
returned: success
type: str
sample: /path/to/file.txt
src:
description: Source file used for the copy on the target machine
description: Source file used for the copy on the target machine.
returned: changed
type: str
sample: /home/httpd/.ansible/tmp/ansible-tmp-1423796390.97-147729857856000/source
md5sum:
description: MD5 checksum of the file after running copy
description: MD5 checksum of the file after running copy.
returned: when supported
type: str
sample: 2a5aeecc61dc98c4d780b14b330e3282
checksum:
description: SHA1 checksum of the file after running copy
description: SHA1 checksum of the file after running copy.
returned: success
type: str
sample: 6e642bb8dd5c2e027bf21dd923337cbb4214f827
backup_file:
description: Name of backup file created
description: Name of backup file created.
returned: changed and if backup=yes
type: str
sample: /path/to/file.txt.2015-02-12@22:09~
gid:
description: Group id of the file, after execution
description: Group id of the file, after execution.
returned: success
type: int
sample: 100
group:
description: Group of the file, after execution
description: Group of the file, after execution.
returned: success
type: str
sample: httpd
owner:
description: Owner of the file, after execution
description: Owner of the file, after execution.
returned: success
type: str
sample: httpd
uid:
description: Owner id of the file, after execution
description: Owner id of the file, after execution.
returned: success
type: int
sample: 100
mode:
description: Permissions of the target, after execution
description: Permissions of the target, after execution.
returned: success
type: str
sample: 0644
size:
description: Size of the target, after execution
description: Size of the target, after execution.
returned: success
type: int
sample: 1220
state:
description: State of the target, after execution
description: State of the target, after execution.
returned: success
type: str
sample: file

@ -268,8 +268,8 @@ options:
type: str
ctstate:
description:
- C(ctstate) is a list of the connection states to match in the conntrack module.
- Possible states are C(INVALID), C(NEW), C(ESTABLISHED), C(RELATED), C(UNTRACKED), C(SNAT), C(DNAT)
- A list of the connection states to match in the conntrack module.
- Possible values are C(INVALID), C(NEW), C(ESTABLISHED), C(RELATED), C(UNTRACKED), C(SNAT), C(DNAT).
type: list
elements: str
default: []
@ -310,7 +310,7 @@ options:
reject_with:
description:
- 'Specifies the error packet type to return while rejecting. It implies
"jump: REJECT"'
"jump: REJECT".'
type: str
version_added: "2.1"
icmp_type:
@ -346,14 +346,14 @@ options:
EXAMPLES = r'''
- name: Block specific IP
iptables:
ansible.builtin.iptables:
chain: INPUT
source: 8.8.8.8
jump: DROP
become: yes
- name: Forward port 80 to 8600
iptables:
ansible.builtin.iptables:
table: nat
chain: PREROUTING
in_interface: eth0
@ -366,14 +366,14 @@ EXAMPLES = r'''
become: yes
- name: Allow related and established connections
iptables:
ansible.builtin.iptables:
chain: INPUT
ctstate: ESTABLISHED,RELATED
jump: ACCEPT
become: yes
- name: Allow new incoming SYN packets on TCP port 22 (SSH)
iptables:
ansible.builtin.iptables:
chain: INPUT
protocol: tcp
destination_port: 22
@ -383,14 +383,14 @@ EXAMPLES = r'''
comment: Accept new SSH connections.
- name: Match on IP ranges
iptables:
ansible.builtin.iptables:
chain: FORWARD
src_range: 192.168.1.100-192.168.1.199
dst_range: 10.0.0.1-10.0.0.50
jump: ACCEPT
- name: Tag all outbound tcp packets with DSCP mark 8
iptables:
ansible.builtin.iptables:
chain: OUTPUT
jump: DSCP
table: mangle
@ -398,7 +398,7 @@ EXAMPLES = r'''
protocol: tcp
- name: Tag all outbound tcp packets with DSCP DiffServ class CS1
iptables:
ansible.builtin.iptables:
chain: OUTPUT
jump: DSCP
table: mangle
@ -406,7 +406,7 @@ EXAMPLES = r'''
protocol: tcp
- name: Insert a rule on line 5
iptables:
ansible.builtin.iptables:
chain: INPUT
protocol: tcp
destination_port: 8080
@ -415,19 +415,19 @@ EXAMPLES = r'''
rule_num: 5
- name: Set the policy for the INPUT chain to DROP
iptables:
ansible.builtin.iptables:
chain: INPUT
policy: DROP
- name: Reject tcp with tcp-reset
iptables:
ansible.builtin.iptables:
chain: INPUT
protocol: tcp
reject_with: tcp-reset
ip_version: ipv4
- name: Set tcp flags
iptables:
ansible.builtin.iptables:
chain: OUTPUT
jump: DROP
protocol: tcp
@ -440,20 +440,20 @@ EXAMPLES = r'''
- FIN
- name: Iptables flush filter
iptables:
ansible.builtin.iptables:
chain: "{{ item }}"
flush: yes
with_items: [ 'INPUT', 'FORWARD', 'OUTPUT' ]
- name: Iptables flush nat
iptables:
ansible.builtin.iptables:
table: nat
chain: '{{ item }}'
flush: yes
with_items: [ 'INPUT', 'OUTPUT', 'PREROUTING', 'POSTROUTING' ]
- name: Log packets arriving into an user-defined chain
iptables:
ansible.builtin.iptables:
chain: LOGGING
action: append
state: present

@ -30,14 +30,12 @@ options:
facts."
type: list
elements: str
required: false
default: "all"
gather_timeout:
version_added: "2.2"
description:
- Set the default timeout in seconds for individual fact gathering.
type: int
required: false
default: 10
filter:
version_added: "1.1"
@ -48,7 +46,6 @@ options:
and the default has became an empty list. A simple string is
still accepted and works as a single pattern. The behaviour
prior to Ansible 2.11 remains.
required: false
type: list
elements: str
default: []
@ -68,7 +65,6 @@ options:
which outputs an object. This object will be formatted by Ansible as json so the
script should be outputting a raw hashtable, array, or other primitive object.
type: path
required: false
default: /etc/ansible/facts.d
description:
- This module is automatically called by playbooks to gather useful
@ -90,6 +86,7 @@ notes:
C(filter) as this is provided by a simpler implementation of the module.
- This module is also supported for Windows targets.
- This module should be run with elevated privileges on BSD systems to gather facts like ansible_product_version.
- Supports C(check_mode).
author:
- "Ansible Core Team"
- "Michael DeHaan"
@ -97,51 +94,51 @@ author:
EXAMPLES = """
# Display facts from all hosts and store them indexed by I(hostname) at C(/tmp/facts).
# ansible all -m setup --tree /tmp/facts
# ansible all -m ansible.builtin.setup --tree /tmp/facts
# Display only facts regarding memory found by ansible on all hosts and output them.
# ansible all -m setup -a 'filter=ansible_*_mb'
# ansible all -m ansible.builtin.setup -a 'filter=ansible_*_mb'
# Display only facts returned by facter.
# ansible all -m setup -a 'filter=facter_*'
# ansible all -m ansible.builtin.setup -a 'filter=facter_*'
# Collect only facts returned by facter.
# ansible all -m setup -a 'gather_subset=!all,!any,facter'
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,!any,facter'
- name: Collect only facts returned by facter
setup:
ansible.builtin.setup:
gather_subset:
- '!all'
- '!any'
- facter
- name: Collect only selected facts
setup:
ansible.builtin.setup:
filter:
- 'ansible_distribution'
- 'ansible_machine_id'
- 'ansible_*_mb'
# Display only facts about certain interfaces.
# ansible all -m setup -a 'filter=ansible_eth[0-2]'
# ansible all -m ansible.builtin.setup -a 'filter=ansible_eth[0-2]'
# Restrict additional gathered facts to network and virtual (includes default minimum facts)
# ansible all -m setup -a 'gather_subset=network,virtual'
# ansible all -m ansible.builtin.setup -a 'gather_subset=network,virtual'
# Collect only network and virtual (excludes default minimum facts)
# ansible all -m setup -a 'gather_subset=!all,!any,network,virtual'
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,!any,network,virtual'
# Do not call puppet facter or ohai even if present.
# ansible all -m setup -a 'gather_subset=!facter,!ohai'
# ansible all -m ansible.builtin.setup -a 'gather_subset=!facter,!ohai'
# Only collect the default minimum amount of facts:
# ansible all -m setup -a 'gather_subset=!all'
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all'
# Collect no facts, even the default minimum subset of facts:
# ansible all -m setup -a 'gather_subset=!all,!min'
# ansible all -m ansible.builtin.setup -a 'gather_subset=!all,!min'
# Display facts from Windows hosts with custom facts stored in C(C:\\custom_facts).
# ansible windows -m setup -a "fact_path='c:\\custom_facts'"
# ansible windows -m ansible.builtin.setup -a "fact_path='c:\\custom_facts'"
"""
# import module snippets

@ -99,37 +99,37 @@ author:
EXAMPLES = r'''
- name: Execute the command in remote shell; stdout goes to the specified file on the remote
shell: somescript.sh >> somelog.txt
ansible.builtin.shell: somescript.sh >> somelog.txt
- name: Change the working directory to somedir/ before executing the command
shell: somescript.sh >> somelog.txt
ansible.builtin.shell: somescript.sh >> somelog.txt
args:
chdir: somedir/
# You can also use the 'args' form to provide the options.
- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist
shell: somescript.sh >> somelog.txt
ansible.builtin.shell: somescript.sh >> somelog.txt
args:
chdir: somedir/
creates: somelog.txt
# You can also use the 'cmd' parameter instead of free form format.
- name: This command will change the working directory to somedir/
shell:
ansible.builtin.shell:
cmd: ls -l | grep log
chdir: somedir/
- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
shell: cat < /tmp/*txt
ansible.builtin.shell: cat < /tmp/*txt
args:
executable: /bin/bash
- name: Run a command using a templated variable (always use quote filter to avoid injection)
shell: cat {{ myfile|quote }}
ansible.builtin.shell: cat {{ myfile|quote }}
# You can use shell to run other executables to perform actions inline
- name: Run expect to wait for a successful PXE boot via out-of-band CIMC
shell: |
ansible.builtin.shell: |
set timeout 300
spawn ssh admin@{{ cimc_host }}
@ -149,7 +149,7 @@ EXAMPLES = r'''
# Disabling warnings
- name: Using curl to connect to a host via SOCKS proxy (unsupported in uri). Ordinarily this would throw a warning
shell: curl --socks5 localhost:9000 http://www.ansible.com
ansible.builtin.shell: curl --socks5 localhost:9000 http://www.ansible.com
args:
warn: no
'''
@ -161,47 +161,47 @@ msg:
type: bool
sample: True
start:
description: The command execution start time
description: The command execution start time.
returned: always
type: str
sample: '2016-02-25 09:18:26.429568'
end:
description: The command execution end time
description: The command execution end time.
returned: always
type: str
sample: '2016-02-25 09:18:26.755339'
delta:
description: The command execution delta time
description: The command execution delta time.
returned: always
type: str
sample: '0:00:00.325771'
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: str
sample: 'rabbitmqctl join_cluster rabbit@master'
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 …']

@ -28,6 +28,7 @@ notes:
- This module returns an 'in memory' base64 encoded version of the file, take
into account that this will require at least twice the RAM as the original file size.
- This module is also supported for Windows targets.
- Supports C(check_mode).
seealso:
- module: ansible.builtin.fetch
author:
@ -37,11 +38,12 @@ author:
EXAMPLES = r'''
- name: Find out what the remote machine's mounts are
slurp:
ansible.builtin.slurp:
src: /proc/mounts
register: mounts
- debug:
- name: Print returned information
ansible.builtin.debug:
msg: "{{ mounts['content'] | b64decode }}"
# From the commandline, find the pid of the remote machine's sshd
@ -56,6 +58,8 @@ EXAMPLES = r'''
# 2179
'''
RETURN = r'''#'''
import base64
import os

@ -50,18 +50,18 @@ author:
EXAMPLES = """
- name: Create temporary build directory
tempfile:
ansible.builtin.tempfile:
state: directory
suffix: build
- name: Create temporary file
tempfile:
ansible.builtin.tempfile:
state: file
suffix: temp
register: tempfile_1
- name: Use the registered var and the file module to remove the temporary file
file:
ansible.builtin.file:
path: "{{ tempfile_1.path }}"
state: absent
when: tempfile_1.path is defined
@ -69,7 +69,7 @@ EXAMPLES = """
RETURN = '''
path:
description: Path to created file or directory
description: Path to created file or directory.
returned: success
type: str
sample: "/tmp/ansible.bMlvdk"

@ -14,7 +14,7 @@ DOCUMENTATION = r'''
---
module: template
version_added: historical
short_description: Template a file out to a remote server
short_description: Template a file out to a target host
options:
follow:
description:
@ -43,7 +43,7 @@ extends_documentation_fragment:
EXAMPLES = r'''
- name: Template a file to /etc/file.conf
template:
ansible.builtin.template:
src: /mytemplates/foo.j2
dest: /etc/file.conf
owner: bin
@ -51,7 +51,7 @@ EXAMPLES = r'''
mode: '0644'
- name: Template a file, using symbolic modes (equivalent to 0644)
template:
ansible.builtin.template:
src: /mytemplates/foo.j2
dest: /etc/file.conf
owner: bin
@ -59,7 +59,7 @@ EXAMPLES = r'''
mode: u=rw,g=r,o=r
- name: Copy a version of named.conf that is dependent on the OS. setype obtained by doing ls -Z /etc/named.conf on original file
template:
ansible.builtin.template:
src: named.conf_{{ ansible_os_family }}.j2
dest: /etc/named.conf
group: named
@ -67,19 +67,19 @@ EXAMPLES = r'''
mode: 0640
- name: Create a DOS-style text file from a template
template:
ansible.builtin.template:
src: config.ini.j2
dest: /share/windows/config.ini
newline_sequence: '\r\n'
- name: Copy a new sudoers file into place, after passing validation with visudo
template:
ansible.builtin.template:
src: /mine/sudoers
dest: /etc/sudoers
validate: /usr/sbin/visudo -cf %s
- name: Update sshd configuration safely, avoid locking yourself out
template:
ansible.builtin.template:
src: etc/ssh/sshd_config.j2
dest: /etc/ssh/sshd_config
owner: root

Loading…
Cancel
Save