From aa2f3edb49dd6e999e67798fa7bdd960632e147f Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Wed, 3 Oct 2018 00:22:30 +0200 Subject: [PATCH] Docs: Clean up of 'blockinfile' module docs (#46331) * Docs: Clean up of 'blockinfile' module docs This is part of a series of module doc cleanups. * A few more fixes after review --- lib/ansible/modules/files/blockinfile.py | 113 +++++++++--------- .../utils/module_docs_fragments/validate.py | 33 ++--- 2 files changed, 67 insertions(+), 79 deletions(-) diff --git a/lib/ansible/modules/files/blockinfile.py b/lib/ansible/modules/files/blockinfile.py index 50977ffd1f..75f3c164d3 100644 --- a/lib/ansible/modules/files/blockinfile.py +++ b/lib/ansible/modules/files/blockinfile.py @@ -12,102 +12,103 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', 'status': ['preview'], 'supported_by': 'core'} - -DOCUMENTATION = """ +DOCUMENTATION = r''' --- module: blockinfile -author: - - YAEGASHI Takeshi (@yaegashi) -extends_documentation_fragment: - - files - - validate short_description: Insert/update/remove a text block surrounded by marker lines version_added: '2.0' description: - - This module will insert/update/remove a block of multi-line text - surrounded by customizable marker lines. +- This module will insert/update/remove a block of multi-line text + surrounded by customizable marker lines. +author: +- Yaegashi Takeshi (@yaegashi) options: path: description: - - The file to modify. - - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name). + - The file to modify. + - Before Ansible 2.3 this option was only usable as I(dest), I(destfile) and I(name). + required: yes + type: path aliases: [ dest, destfile, name ] - required: true state: description: - - Whether the block should be there or not. + - Whether the block should be there or not. + type: str choices: [ absent, present ] default: present marker: description: - - The marker line template. - "{mark}" will be replaced with the values in marker_begin - (default="BEGIN") and marker_end (default="END"). + - The marker line template. + - C({mark}) will be replaced with the values C(in marker_begin) (default="BEGIN") and C(marker_end) (default="END"). + type: str default: '# {mark} ANSIBLE MANAGED BLOCK' block: description: - - The text to insert inside the marker lines. - If it's missing or an empty string, - the block will be removed as if C(state) were specified to C(absent). + - The text to insert inside the marker lines. + - If it is missing or an empty string, the block will be removed as if C(state) were specified to C(absent). + type: str aliases: [ content ] default: '' insertafter: description: - - If specified, the block will be inserted after the last match of - specified regular expression. A special value is available; C(EOF) for - inserting the block at the end of the file. If specified regular - expression has no matches, C(EOF) will be used instead. + - If specified, the block will be inserted after the last match of specified regular expression. + - A special value is available; C(EOF) for inserting the block at the end of the file. + - If specified regular expression has no matches, C(EOF) will be used instead. + type: str default: EOF choices: [ EOF, '*regex*' ] insertbefore: description: - - If specified, the block will be inserted before the last match of - specified regular expression. A special value is available; C(BOF) for - inserting the block at the beginning of the file. If specified regular - expression has no matches, the block will be inserted at the end of the - file. + - If specified, the block will be inserted before the last match of specified regular expression. + - A special value is available; C(BOF) for inserting the block at the beginning of the file. + - If specified regular expression has no matches, the block will be inserted at the end of the file. + type: str choices: [ BOF, '*regex*' ] create: description: - - Create a new file if it doesn't exist. + - Create a new file if it does not exist. type: bool - default: 'no' + default: no backup: description: - - Create a backup file including the timestamp information so you can - get the original file back if you somehow clobbered it incorrectly. + - 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 marker_begin: description: - - This will be inserted at {mark} in the opening ansible block marker. - default: 'BEGIN' - version_added: "2.5" + - This will be inserted at C({mark}) in the opening ansible block marker. + type: str + default: BEGIN + version_added: '2.5' marker_end: required: false description: - - This will be inserted at {mark} in the closing ansible block marker. - default: 'END' - version_added: "2.5" - + - This will be inserted at C({mark}) in the closing ansible block marker. + type: str + default: END + version_added: '2.5' notes: - This module supports check mode. - When using 'with_*' loops be aware that if you do not set a unique mark the block will be overwritten on each iteration. - As of Ansible 2.3, the I(dest) option has been changed to I(path) as default, but I(dest) still works as well. - - Option I(follow) has been removed in version 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense. - - When more then one block should be handled in **one** file you **must** change the I(marker) per task -""" + - Option I(follow) has been removed in Ansible 2.5, because this module modifies the contents of the file so I(follow=no) doesn't make sense. + - When more then one block should be handled in one file you must change the I(marker) per task. +extends_documentation_fragment: +- files +- validate +''' -EXAMPLES = r""" -# Before 2.3, option 'dest' or 'name' was used instead of 'path' -- name: insert/update "Match User" configuration block in /etc/ssh/sshd_config +EXAMPLES = r''' +# Before Ansible 2.3, option 'dest' or 'name' was used instead of 'path' +- name: Insert/Update "Match User" configuration block in /etc/ssh/sshd_config blockinfile: path: /etc/ssh/sshd_config block: | Match User ansible-agent PasswordAuthentication no -- name: insert/update eth0 configuration stanza in /etc/network/interfaces +- name: Insert/Update eth0 configuration stanza in /etc/network/interfaces (it might be better to copy files into /etc/network/interfaces.d/) blockinfile: path: /etc/network/interfaces @@ -116,14 +117,14 @@ EXAMPLES = r""" address 192.0.2.23 netmask 255.255.255.0 -- name: insert/update configuration using a local file and validate it +- name: Insert/Update configuration using a local file and validate it blockinfile: block: "{{ lookup('file', './local/ssh_config') }}" - dest: "/etc/ssh/ssh_config" + dest: /etc/ssh/ssh_config backup: yes - validate: "/usr/sbin/sshd -T -f %s" + validate: /usr/sbin/sshd -T -f %s -- name: insert/update HTML surrounded by custom markers after line +- name: Insert/Update HTML surrounded by custom markers after line blockinfile: path: /var/www/html/index.html marker: "" @@ -132,7 +133,7 @@ EXAMPLES = r"""

Welcome to {{ ansible_hostname }}

Last updated on {{ ansible_date_time.iso8601 }}

-- name: remove HTML as well as surrounding markers +- name: Remove HTML as well as surrounding markers blockinfile: path: /var/www/html/index.html marker: "" @@ -145,10 +146,10 @@ EXAMPLES = r""" {{ item.ip }} {{ item.name }} marker: "# {mark} ANSIBLE MANAGED BLOCK {{ item.name }}" with_items: - - { name: host1, ip: 10.10.1.10 } - - { name: host2, ip: 10.10.1.11 } - - { name: host3, ip: 10.10.1.12 } -""" + - { name: host1, ip: 10.10.1.10 } + - { name: host2, ip: 10.10.1.11 } + - { name: host3, ip: 10.10.1.12 } +''' import re import os diff --git a/lib/ansible/utils/module_docs_fragments/validate.py b/lib/ansible/utils/module_docs_fragments/validate.py index f253c67d19..4b5d852a89 100644 --- a/lib/ansible/utils/module_docs_fragments/validate.py +++ b/lib/ansible/utils/module_docs_fragments/validate.py @@ -1,29 +1,16 @@ -# Copyright (c) 2015 Ansible, Inc -# -# 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 . +# -*- coding: utf-8 -*- + +# Copyright: (c) 2015, Ansible, Inc +# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt) class ModuleDocFragment(object): - # Standard documentation fragment - DOCUMENTATION = ''' + DOCUMENTATION = r''' options: - 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 example below. - The command is passed securely so shell features like expansion and pipes won't work. + 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 examples below. + - The command is passed securely so shell features like expansion and pipes will not work. '''