Clean up common module docs (#45888)

Some of the older modules have evolved documentation that does not follow a consistent style. This is a clean-up in form and style.
6 years ago · 04de52da2c
parent 698c8059e9
commit 04de52da2c
2 changed files with 37 additions and 35 deletions
--- a/lib/ansible/modules/commands/command.py
+++ b/lib/ansible/modules/commands/command.py
@ -3,7 +3,6 @@

 # Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
 # Copyright: (c) 2016, Toshio Kuratomi <tkuratomi@ansible.com>
-#
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

 from __future__ import absolute_import, division, print_function
@ -14,10 +13,10 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'status': ['stableinterface'],
                    'supported_by': 'core'}

-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: command
-short_description: Executes a command on a remote node
+short_description: Execute commands on targets
 version_added: historical
 description:
     - The C(command) module takes the command name followed by a list of space-delimited arguments.
@ -29,8 +28,9 @@ description:
 options:
  free_form:
    description:
-      - The command module takes a free form command to run.  There is no parameter actually named 'free form'.
-        See the examples!
+      - The command module takes a free form command to run.
+      - There is no actual parameter named 'free form'.
+      - See the examples on how to use this module.
    required: yes
  argv:
    description:
@ -50,14 +50,14 @@ options:
    version_added: "0.6"
  warn:
    description:
-      - If command_warnings are on in ansible.cfg, do not warn about this particular line if set to C(no).
+      - Enable or disable task warnings.
    type: bool
-    default: 'yes'
+    default: yes
    version_added: "1.8"
  stdin:
-    version_added: "2.4"
    description:
      - Set the stdin of the command directly to the specified value.
+    version_added: "2.4"
 notes:
    -  If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(shell) module instead.
       Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to
@ -73,7 +73,7 @@ author:
    - Michael DeHaan
 '''

-EXAMPLES = '''
+EXAMPLES = r'''
 - name: return motd to registered var
  command: cat /etc/motd
  register: mymotd
@ -102,7 +102,7 @@ EXAMPLES = '''
  register: myoutput
 '''

-RETURN = '''
+RETURN = r'''
 cmd:
  description: the cmd that was run on the remote machine
  returned: always
--- a/lib/ansible/modules/commands/shell.py
+++ b/lib/ansible/modules/commands/shell.py
@ -1,7 +1,10 @@
-# Copyright: Ansible Project
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
+# Copyright: (c) 2018, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

-# # There is no actual shell module source, when you use 'shell' in ansible,
+# There is no actual shell module source, when you use 'shell' in ansible,
 # it runs the 'command' module with special arguments and it behaves differently.
 # See the command source and the comment "#USE_SHELL".

@ -14,47 +17,49 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                    'supported_by': 'core'}


-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: shell
-short_description: Execute commands in nodes.
+short_description: Execute shell commands on targets
 description:
     - The C(shell) module takes the command name followed by a list of space-delimited arguments.
-       It is almost exactly like the M(command) module but runs
+     - It is almost exactly like the M(command) module but runs
       the command through a shell (C(/bin/sh)) on the remote node.
     - For Windows targets, use the M(win_shell) module instead.
 version_added: "0.2"
 options:
  free_form:
    description:
-      - The shell module takes a free form command to run, as a string.  There's not an actual
-        option named "free form".  See the examples!
-    required: true
+      - The shell module takes a free form command to run, as a string.
+      - There is no actual parameter named 'free form'.
+      - See the examples on how to use this module.
+    required: yes
  creates:
    description:
-      - a filename, when it already exists, this step will B(not) be run.
+      - A filename, when it already exists, this step will B(not) be run.
  removes:
    description:
-      - a filename, when it does not exist, this step will B(not) be run.
+      - A filename, when it does not exist, this step will B(not) be run.
    version_added: "0.8"
  chdir:
    description:
-      - cd into this directory before running the command
+      - Change into this directory before running the command.
    version_added: "0.6"
  executable:
    description:
-      - change the shell used to execute the command. Should be an absolute path to the executable.
+      - Change the shell used to execute the command.
+      - This expects an absolute path to the executable.
    version_added: "0.9"
  warn:
    description:
-      - if command warnings are on in ansible.cfg, do not warn about this particular line if set to no/false.
+      - Enable or disable task warnings.
    type: bool
-    default: 'yes'
+    default: yes
    version_added: "1.8"
  stdin:
-    version_added: "2.4"
    description:
      - Set the stdin of the command directly to the specified value.
+    version_added: "2.4"
 notes:
  -  If you want to execute a command securely and predictably, it may be
     better to use the M(command) module instead. Best practices when writing
@ -68,15 +73,12 @@ notes:
  -  To sanitize any variables passed to the shell module, you should use
     "{{ var | quote }}" instead of just "{{ var }}" to make sure they don't include evil things like semicolons.
  - For Windows targets, use the M(win_shell) module instead.
-  - Rather than using here documents to create multi-line scripts inside playbooks,
-    use the M(script) module instead.
-requirements: [ ]
 author:
    - Ansible Core Team
    - Michael DeHaan
 '''

-EXAMPLES = '''
+EXAMPLES = r'''
 - name: Execute the command in remote shell; stdout goes to the specified file on the remote.
  shell: somescript.sh >> somelog.txt

@ -107,13 +109,13 @@ EXAMPLES = '''
    spawn ssh admin@{{ cimc_host }}

    expect "password:"
-    send "{{ cimc_password }}\\n"
+    send "{{ cimc_password }}\n"

-    expect "\\n{{ cimc_name }}"
-    send "connect host\\n"
+    expect "\n{{ cimc_name }}"
+    send "connect host\n"

    expect "pxeboot.n12"
-    send "\\n"
+    send "\n"

    exit 0
  args:
@ -124,10 +126,10 @@ EXAMPLES = '''
 - 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
  args:
-    warn: False
+    warn: no
 '''

-RETURN = '''
+RETURN = r'''
 msg:
    description: changed
    returned: always