From d6a581502fa0b86263739ed4d046f47c71b218ac Mon Sep 17 00:00:00 2001
From: Dag Wieers <dag@wieers.com>
Date: Wed, 3 Oct 2018 21:56:19 +0200
Subject: [PATCH] Docs: Clean up of 'assemble' module docs (#46328)
This is part of a series of module doc cleanups.
---
lib/ansible/modules/files/assemble.py | 89 ++++++++++++++-------------
1 file changed, 47 insertions(+), 42 deletions(-)
diff --git a/lib/ansible/modules/files/assemble.py b/lib/ansible/modules/files/assemble.py
index d33f42c3147..cf49803eeb9 100644
--- a/lib/ansible/modules/files/assemble.py
+++ b/lib/ansible/modules/files/assemble.py
@@ -13,85 +13,90 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
'status': ['stableinterface'],
'supported_by': 'core'}
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
---
module: assemble
-short_description: Assembles a configuration file from fragments
+short_description: Assemble configuration files from fragments
description:
- - Assembles a configuration file from fragments. Often a particular
- program will take a single configuration file and does not support a
- C(conf.d) style structure where it is easy to build up the configuration
- from multiple sources. C(assemble) will take a directory of files that can be
- local or have already been transferred to the system, and concatenate them
- together to produce a destination file. Files are assembled in string sorting order.
- Puppet calls this idea I(fragments).
-version_added: "0.5"
+- Assembles a configuration file from fragments.
+- Often a particular program will take a single configuration file and does not support a
+ C(conf.d) style structure where it is easy to build up the configuration
+ from multiple sources. C(assemble) will take a directory of files that can be
+ local or have already been transferred to the system, and concatenate them
+ together to produce a destination file.
+- Files are assembled in string sorting order.
+- Puppet calls this idea I(fragments).
+- This module is also supported for Windows targets.
+notes:
+- This module is also supported for Windows targets.
+- See also M(copy) and M(template).
+version_added: '0.5'
options:
src:
description:
- - An already existing directory full of source files.
+ - An already existing directory full of source files.
required: true
dest:
description:
- - A file to create using the concatenation of all of the source files.
+ - A file to create using the concatenation of all of the source files.
required: true
backup:
description:
- - Create a backup file (if C(yes)), including the timestamp information so
- you can get the original file back if you somehow clobbered it
- incorrectly.
+ - Create a backup file (if C(yes)), including the timestamp information so
+ you can get the original file back if you somehow clobbered it
+ incorrectly.
type: bool
- default: 'no'
+ default: no
delimiter:
description:
- - A delimiter to separate the file contents.
- version_added: "1.4"
+ - A delimiter to separate the file contents.
+ version_added: '1.4'
remote_src:
description:
- - If False, it will search for src at originating/master machine, if True it will
- go to the remote/target machine for the src. Default is True.
+ - If C(no), it will search for src at originating/master machine.
+ - If C(yes), it will go to the remote/target machine for the src.
type: bool
- default: 'yes'
- version_added: "1.4"
+ default: yes
+ version_added: '1.4'
regexp:
description:
- - Assemble files only if C(regex) matches the filename. If not set,
- all files are assembled. All "\\" (backslash) must be escaped as
- "\\\\" to comply yaml syntax. Uses Python regular expressions; see
- U(http://docs.python.org/2/library/re.html).
+ - Assemble files only if C(regex) matches the filename.
+ - If not set, all files are assembled.
+ - Every "\" (backslash) must be escaped as "\\" to comply to YAML syntax.
+ - Uses L(Python regular expressions,http://docs.python.org/2/library/re.html).
ignore_hidden:
description:
- - A boolean that controls if files that start with a '.' will be included or not.
+ - A boolean that controls if files that start with a '.' will be included or not.
type: bool
- default: 'no'
- version_added: "2.0"
+ default: no
+ version_added: '2.0'
validate:
description:
- - The validation command to run before copying into place. The path to the file to
- validate is passed in via '%s' which must be present as in the sshd example below.
- The command is passed securely so shell features like expansion and pipes won't work.
- version_added: "2.0"
+ - The validation command to run before copying into place.
+ - The path to the file to validate is passed in via '%s' which must be present as in the sshd example below.
+ - The command is passed securely so shell features like expansion and pipes won't work.
+ version_added: '2.0'
author:
- Stephen Fromm (@sfromm)
extends_documentation_fragment:
- - files
- - decrypt
+- files
+- decrypt
'''
-EXAMPLES = '''
-# Example from Ansible Playbooks
-- assemble:
+EXAMPLES = r'''
+- name: Assemble from fragments from a directory
+ assemble:
src: /etc/someapp/fragments
dest: /etc/someapp/someapp.conf
-# When a delimiter is specified, it will be inserted in between each fragment
-- assemble:
+- name: Inserted provided delimiter in between each fragment
+ assemble:
src: /etc/someapp/fragments
dest: /etc/someapp/someapp.conf
delimiter: '### START FRAGMENT ###'
-# Copy a new "sshd_config" file into place, after passing validation with sshd
-- assemble:
+- name: Assemble a new "sshd_config" file into place, after passing validation with sshd
+ assemble:
src: /etc/ssh/conf.d/
dest: /etc/ssh/sshd_config
validate: '/usr/sbin/sshd -t -f %s'