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

@@ -12,102 +12,103 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = """
 ---
 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
+- This module will insert/update/remove a block of multi-line text
-    surrounded by customizable marker lines.
+  surrounded by customizable marker lines.
+author:
+- Yaegashi Takeshi (@yaegashi)
 options:
   path:
     description:
-      - The file to modify.
+    - The file to modify.
-      - Before 2.3 this option was only usable as I(dest), I(destfile) and I(name).
+    - 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.
+    - The marker line template.
-        "{mark}" will be replaced with the values in marker_begin
+    - C({mark}) will be replaced with the values C(in marker_begin) (default="BEGIN") and C(marker_end) (default="END").
-        (default="BEGIN") and marker_end (default="END").
+    type: str
     default: '# {mark} ANSIBLE MANAGED BLOCK'
   block:
     description:
-      - The text to insert inside the marker lines.
+    - The text to insert inside the marker lines.
-        If it's missing or an empty string,
+    - If it is missing or an empty string, the block will be removed as if C(state) were specified to C(absent).
-        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
+    - If specified, the block will be inserted after the last match of specified regular expression.
-        specified regular expression. A special value is available; C(EOF) for
+    - A special value is available; C(EOF) for inserting the block at the end of the file.
-        inserting the block at the end of the file.  If specified regular
+    - If specified regular expression has no matches, C(EOF) will be used instead.
-        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
+    - If specified, the block will be inserted before the last match of specified regular expression.
-        specified regular expression. A special value is available; C(BOF) for
+    - A special value is available; C(BOF) for inserting the block at the beginning of the file.
-        inserting the block at the beginning of the file.  If specified regular
+    - If specified regular expression has no matches, the block will be inserted at the end of the file.
-        expression has no matches, the block will be inserted at the end of the
+    type: str
-        file.
     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
+    - Create a backup file including the timestamp information so you can
-        get the original file back if you somehow clobbered it incorrectly.
+      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.
+    - This will be inserted at C({mark}) in the opening ansible block marker.
-    default: 'BEGIN'
+    type: str
-    version_added: "2.5"
+    default: BEGIN
+    version_added: '2.5'
   marker_end:
     required: false
     description:
-      - This will be inserted at {mark} in the closing ansible block marker.
+    - This will be inserted at C({mark}) in the closing ansible block marker.
-    default: 'END'
+    type: str
-    version_added: "2.5"
+    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.
+  - 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
+  - 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"""
+EXAMPLES = r'''
-# Before 2.3, option 'dest' or 'name' was used instead of 'path'
+# 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
+- 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 <body> line
+- name: Insert/Update HTML surrounded by custom markers after <body> line
   blockinfile:
     path: /var/www/html/index.html
     marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
@@ -132,7 +133,7 @@ EXAMPLES = r"""
       <h1>Welcome to {{ ansible_hostname }}</h1>
       <p>Last updated on {{ ansible_date_time.iso8601 }}</p>
 
-- name: remove HTML as well as surrounding markers
+- name: Remove HTML as well as surrounding markers
   blockinfile:
     path: /var/www/html/index.html
     marker: "<!-- {mark} ANSIBLE MANAGED BLOCK -->"
@@ -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: host1, ip: 10.10.1.10 }
-    - { name: host2, ip: 10.10.1.11 }
+  - { name: host2, ip: 10.10.1.11 }
-    - { name: host3, ip: 10.10.1.12 }
+  - { name: host3, ip: 10.10.1.12 }
-"""
+'''
 
 import re
 import os

lib/ansible/utils/module_docs_fragments/validate.py

@@ -1,29 +1,16 @@
-# Copyright (c) 2015 Ansible, Inc
+# -*- coding: utf-8 -*-
-#
+
-# This file is part of Ansible
+# Copyright: (c) 2015, Ansible, Inc
-#
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
-# 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 <http://www.gnu.org/licenses/>.
 
 
 class ModuleDocFragment(object):
-
     # Standard documentation fragment
-    DOCUMENTATION = '''
+    DOCUMENTATION = r'''
 options:
-    validate:
+  validate:
-      description:
+    description:
-       - The validation command to run before copying into place. The path to the file to
+    - The validation command to run before copying into place.
-         validate is passed in via '%s' which must be present as in the example below.
+    - 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 won't work.
+    - The command is passed securely so shell features like expansion and pipes will not work.
 '''