From be0dc34b6fed0f8a272de87e049a29b964d1702c Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Thu, 4 Oct 2018 05:12:25 +0200 Subject: [PATCH] Docs: Clean up of 'template' module docs (#46297) * Docs: Clean up of 'template' module docs * Changed influenced by review comments --- lib/ansible/modules/files/template.py | 160 +++++++++--------- .../utils/module_docs_fragments/files.py | 92 +++++----- 2 files changed, 123 insertions(+), 129 deletions(-) diff --git a/lib/ansible/modules/files/template.py b/lib/ansible/modules/files/template.py index 4f6b9a58b5..f93a72d233 100644 --- a/lib/ansible/modules/files/template.py +++ b/lib/ansible/modules/files/template.py @@ -1,7 +1,11 @@ -# this is a virtual module that is entirely implemented server side +#!/usr/bin/python +# -*- coding: utf-8 -*- + # Copyright: (c) 2017, Ansible Project # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) +# This is a virtual module that is entirely implemented as an action plugin and runs on the controller + from __future__ import absolute_import, division, print_function __metaclass__ = type @@ -13,156 +17,152 @@ DOCUMENTATION = r''' --- module: template version_added: historical -short_description: Templates a file out to a remote server +short_description: Template a file out to a remote server description: - - Templates are processed by the Jinja2 templating language - (U(http://jinja.pocoo.org/docs/)) - documentation on the template - formatting can be found in the Template Designer Documentation - (U(http://jinja.pocoo.org/docs/templates/)). - - "Six additional variables can be used in templates: - C(ansible_managed) (configurable via the C(defaults) section of C(ansible.cfg)) contains a string which can be used to - describe the template name, host, modification time of the template file and the owner uid. - C(template_host) contains the node name of the template's machine. - C(template_uid) is the numeric user id of the owner. - C(template_path) is the path of the template. - C(template_fullpath) is the absolute path of the template. - C(template_run_date) is the date that the template was rendered." +- Templates are processed by the L(Jinja2 templating language,http://jinja.pocoo.org/docs/). +- Documentation on the template formatting can be found in the + L(Template Designer Documentation,http://jinja.pocoo.org/docs/templates/). +- The six additional variables, listed below, can be used in template. +- C(ansible_managed) (configurable via the C(defaults) section of C(ansible.cfg)) contains a string which can be used to + describe the template name, host, modification time of the template file and the owner uid. +- C(template_host) contains the node name of the template's machine. +- C(template_uid) is the numeric user id of the owner. +- C(template_path) is the path of the template. +- C(template_fullpath) is the absolute path of the template. +- C(template_run_date) is the date that the template was rendered. options: src: description: - - Path of a Jinja2 formatted template on the Ansible controller. This can be a relative or absolute path. - required: true + - Path of a Jinja2 formatted template on the Ansible controller. + - This can be a relative or an absolute path. + required: yes dest: description: - - Location to render the template to on the remote machine. - required: true + - Location to render the template to on the remote machine. + required: yes backup: description: - - Create a backup file including the timestamp information so you can get - the original file back if you somehow clobbered it incorrectly. + - Determine whether a backup should be created. + - When set to C(yes), create a backup file including the timestamp information + so you can get the original file back if you somehow clobbered it incorrectly. type: bool - default: 'no' + default: no newline_sequence: description: - - Specify the newline sequence to use for templating files. + - Specify the newline sequence to use for templating files. choices: [ '\n', '\r', '\r\n' ] default: '\n' version_added: '2.4' block_start_string: description: - - The string marking the beginning of a block. + - The string marking the beginning of a block. default: '{%' version_added: '2.4' block_end_string: description: - - The string marking the end of a block. + - The string marking the end of a block. default: '%}' version_added: '2.4' variable_start_string: description: - - The string marking the beginning of a print statement. + - The string marking the beginning of a print statement. default: '{{' version_added: '2.4' variable_end_string: description: - - The string marking the end of a print statement. + - The string marking the end of a print statement. default: '}}' version_added: '2.4' trim_blocks: description: - - If this is set to True the first newline after a block is removed (block, not variable tag!). + - Determine when newlines should be removed from blocks. + - When set to C(yes) the first newline after a block is removed (block, not variable tag!). type: bool - default: 'yes' + default: yes version_added: '2.4' lstrip_blocks: description: - - If this is set to True leading spaces and tabs are stripped from the start of a line to a block. - Setting this option to True requires Jinja2 version >=2.7. + - Determine when leading spaces and tabs should be stripped. + - When set to C(yes) leading spaces and tabs are stripped from the start of a line to a block. + - This functionality requires Jinja v2.7 or newer. type: bool - default: 'no' + default: no version_added: '2.6' force: description: - - the default is C(yes), which will replace the remote file when contents - are different than the source. If C(no), the file will only be transferred - if the destination does not exist. + - Determine when the file is being transferred if the destination already exists. + - When set to C(yes), replace the remote file when contents are different than the source. + - When set to C(no), the file will only be transferred if the destination does not exist. type: bool - default: 'yes' + default: yes follow: description: - - This flag indicates that filesystem links in the destination, if they exist, should be followed. - - Previous to Ansible 2.4, this was hardcoded as C(yes). + - Determine whether symbolic links should be followed. + - When set to C(yes) symbolic links will be followed, if they exist. + - When set to C(no) symbolic links will not be followed. + - Previous to Ansible 2.4, this was hardcoded as C(yes). type: bool - default: 'no' - version_added: "2.4" - mode: - description: - - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that - modes are actually octal numbers. You must either add a leading zero so that Ansible's - YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it - (like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from - string into number. Giving Ansible a number without following one of these rules will end - up with a decimal number which will have unexpected results. As of version 1.8, the mode - may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)). As of - version 2.6, the mode may also be the special string C(preserve). C(preserve) means that - the file will be given the same permissions as the source file." + default: no + version_added: '2.4' output_encoding: description: - - Overrides the encoding used to write the template file defined by C(dest). - - It defaults to C('utf-8'), but any encoding supported by python can be used. - - The source template file must always be encoded using C('utf-8'), for homogeneity. - default: 'utf-8' - version_added: "2.7" + - Overrides the encoding used to write the template file defined by C(dest). + - It defaults to C(utf-8), but any encoding supported by python can be used. + - The source template file must always be encoded using C(utf-8), for homogeneity. + default: utf-8 + version_added: '2.7' notes: - - For Windows you can use M(win_template) which uses '\\r\\n' as C(newline_sequence). - - Including a string that uses a date in the template will result in the template being marked 'changed' each time - - "Since Ansible version 0.9, templates are loaded with C(trim_blocks=True)." - - "Also, you can override jinja2 settings by adding a special header to template file. - i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False) - which changes the variable interpolation markers to [% var %] instead of {{ var }}. - This is the best way to prevent evaluation of things that look like, but should not be Jinja2. - raw/endraw in Jinja2 will not work as you expect because templates in Ansible are recursively evaluated." - - You can use the C(copy) module with the C(content:) option if you prefer the template inline, - as part of the playbook. +- Including a string that uses a date in the template will result in the template being marked 'changed' each time. +- Since Ansible version 0.9, templates are loaded with C(trim_blocks=True). +- > + Also, you can override jinja2 settings by adding a special header to template file. + i.e. C(#jinja2:variable_start_string:'[%', variable_end_string:'%]', trim_blocks: False) + which changes the variable interpolation markers to C([% var %]) instead of C({{ var }}). + This is the best way to prevent evaluation of things that look like, but should not be Jinja2. +- Using raw/endraw in Jinja2 will not work as you expect because templates in Ansible are recursively + evaluated. +- You can use the M(copy) module with the C(content:) option if you prefer the template inline, + as part of the playbook. +- For Windows you can use M(win_template) which uses '\\r\\n' as C(newline_sequence) by default. author: - - Ansible Core Team - - Michael DeHaan +- Ansible Core Team +- Michael DeHaan extends_documentation_fragment: - - files - - validate +- files +- validate ''' EXAMPLES = r''' -# Example from Ansible Playbooks -- template: +- name: Template a file to /etc/files.conf + template: src: /mytemplates/foo.j2 dest: /etc/file.conf owner: bin group: wheel - mode: 0644 + mode: '0644' -# The same example, but using symbolic modes equivalent to 0644 -- template: +- name: Template a file, using symbolic modes (equivalent to 0644) + template: src: /mytemplates/foo.j2 dest: /etc/file.conf owner: bin group: wheel mode: "u=rw,g=r,o=r" -# Create a DOS-style text file from a template -- template: +- name: Create a DOS-style text file from a template + template: src: config.ini.j2 dest: /share/windows/config.ini newline_sequence: '\r\n' -# Copy a new "sudoers" file into place, after passing validation with visudo -- template: +- name: Copy a new sudoers file into place, after passing validation with visudo + template: src: /mine/sudoers dest: /etc/sudoers validate: '/usr/sbin/visudo -cf %s' -# Update sshd configuration safely, avoid locking yourself out -- template: +- name: Update sshd configuration safely, avoid locking yourself out + template: src: etc/ssh/sshd_config.j2 dest: /etc/ssh/sshd_config owner: root diff --git a/lib/ansible/utils/module_docs_fragments/files.py b/lib/ansible/utils/module_docs_fragments/files.py index b18c86b9a6..372325d2dd 100644 --- a/lib/ansible/utils/module_docs_fragments/files.py +++ b/lib/ansible/utils/module_docs_fragments/files.py @@ -1,19 +1,5 @@ -# (c) 2014, Matt Martz -# -# This file is part of Ansible -# -# Ansible is free software: you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation, either version 3 of the License, or -# (at your option) any later version. -# -# Ansible is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License -# along with Ansible. If not, see . +# Copyright: (c) 2014, Matt Martz +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) class ModuleDocFragment(object): @@ -22,56 +8,64 @@ class ModuleDocFragment(object): # Note: mode is overridden by the copy and template modules so if you change the description # here, you should also change it there. - DOCUMENTATION = """ + DOCUMENTATION = r''' options: mode: description: - - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers. - You must either add a leading zero so that Ansible's YAML parser knows it is an octal - number (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible - receives a string and can do its own conversion from string into number. Giving Ansible a number - without following one of these rules will end up with a decimal number which will have unexpected results. - As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r))." + - The permissions the resulting file or directory should have. + - For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers. + You must either add a leading zero so that Ansible's YAML parser knows it is an octal number + (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible receives + a string and can do its own conversion from string into number. + - Giving Ansible a number without following one of these rules will end up with a decimal + number which will have unexpected results. + - As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or + C(u=rw,g=r,o=r)). + - As of version 2.6, the mode may also be the special string C(preserve). + - When set to C(preserve) the file will be given the same permissions as the source file. owner: description: - - Name of the user that should own the file/directory, as would be fed to I(chown). + - Name of the user that should own the file/directory, as would be fed to I(chown). group: description: - - Name of the group that should own the file/directory, as would be fed to I(chown). + - Name of the group that should own the file/directory, as would be fed to I(chown). seuser: description: - - User part of SELinux file context. Will default to system policy, if - applicable. If set to C(_default), it will use the C(user) portion of the - policy if available. + - The user part of the SELinux file context. + - By default it uses the C(system) policy, where applicable. + - When set to C(_default), it will use the C(user) portion of the policy if available. serole: description: - - Role part of SELinux file context, C(_default) feature works as for I(seuser). + - The role part of the SELinux file context. + - When set to C(_default), it will use the C(role) portion of the policy if available. setype: description: - - Type part of SELinux file context, C(_default) feature works as for I(seuser). + - The type part of the SELinux file context. + - When set to C(_default), it will use the C(type) portion of the policy if available. selevel: description: - - Level part of the SELinux file context. This is the MLS/MCS attribute, - sometimes known as the C(range). C(_default) feature works as for - I(seuser). - default: "s0" + - The level part of the SELinux file context. + - This is the MLS/MCS attribute, sometimes known as the C(range). + - When set to C(_default), it will use the C(level) portion of the policy if available. + default: s0 unsafe_writes: description: - - By default this module uses atomic operations to prevent data - corruption or inconsistent reads from the target files, - but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted files, - which cannot be updated atomically from inside the container and can only be written in an unsafe manner. - - This option allows Ansible to fall back to unsafe methods of - updating files when atomic operations fail (however, it doesn't force Ansible to perform unsafe writes). - IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. + - Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target file. + - By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target files, + but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted files, + which cannot be updated atomically from inside the container and can only be written in an unsafe manner. + - This option allows Ansible to fall back to unsafe methods of updating files when atomic operations fail + (however, it doesn't force Ansible to perform unsafe writes). + - IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. type: bool - default: 'no' - version_added: "2.2" + default: no + version_added: '2.2' attributes: description: - - Attributes the file or directory should have. To get supported flags look at the man page for I(chattr) on the target system. - This string should contain the attributes in the same order as the one displayed by I(lsattr). - - C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to be included in the string. - aliases: ['attr'] - version_added: "2.3" -""" + - The attributes the resulting file or directory should have. + - To get supported flags look at the man page for I(chattr) on the target system. + - This string should contain the attributes in the same order as the one displayed by I(lsattr). + - The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to be included in the string. + aliases: [ attr ] + version_added: '2.3' +'''