From f824b2ce8d8436891feda888fb16a25e449dc87a Mon Sep 17 00:00:00 2001 From: Dag Wieers Date: Mon, 13 Feb 2017 15:02:34 +0100 Subject: [PATCH] Avoid having module documentation links to itself (#21329) * Avoid having module documentation links to itself A lot of modules use M(own_module) in their documentation causing a link in the documentation to itself. * Make note more clear now --- lib/ansible/modules/cloud/amazon/sns_topic.py | 2 +- lib/ansible/modules/cloud/lxd/lxd_container.py | 4 ++-- lib/ansible/modules/commands/command.py | 4 ++-- lib/ansible/modules/commands/expect.py | 2 +- lib/ansible/modules/commands/raw.py | 2 +- lib/ansible/modules/commands/script.py | 2 +- lib/ansible/modules/commands/shell.py | 6 +++--- lib/ansible/modules/files/archive.py | 2 +- lib/ansible/modules/files/assemble.py | 2 +- lib/ansible/modules/files/copy.py | 2 +- lib/ansible/modules/files/file.py | 4 ++-- lib/ansible/modules/files/tempfile.py | 2 +- lib/ansible/modules/files/unarchive.py | 2 +- lib/ansible/modules/monitoring/nagios.py | 4 ++-- lib/ansible/modules/network/asa/asa_command.py | 2 +- lib/ansible/modules/network/dellos6/dellos6_command.py | 2 +- lib/ansible/modules/network/dellos9/dellos9_config.py | 2 +- lib/ansible/modules/network/junos/junos_netconf.py | 2 +- lib/ansible/modules/network/wakeonlan.py | 2 +- lib/ansible/modules/notification/grove.py | 2 +- lib/ansible/modules/notification/hall.py | 2 +- lib/ansible/modules/notification/rocketchat.py | 2 +- lib/ansible/modules/notification/slack.py | 2 +- lib/ansible/modules/notification/sns.py | 2 +- lib/ansible/modules/packaging/language/easy_install.py | 2 +- lib/ansible/modules/source_control/git_config.py | 2 +- lib/ansible/modules/system/known_hosts.py | 2 +- lib/ansible/modules/system/pam_limits.py | 2 +- lib/ansible/modules/web_infrastructure/jenkins_script.py | 2 +- lib/ansible/modules/windows/win_command.py | 4 ++-- lib/ansible/modules/windows/win_copy.py | 2 +- lib/ansible/modules/windows/win_shell.py | 4 ++-- 32 files changed, 40 insertions(+), 40 deletions(-) diff --git a/lib/ansible/modules/cloud/amazon/sns_topic.py b/lib/ansible/modules/cloud/amazon/sns_topic.py index 3f12155acf..2e69b387cc 100644 --- a/lib/ansible/modules/cloud/amazon/sns_topic.py +++ b/lib/ansible/modules/cloud/amazon/sns_topic.py @@ -23,7 +23,7 @@ DOCUMENTATION = """ module: sns_topic short_description: Manages AWS SNS topics and subscriptions description: - - The M(sns_topic) module allows you to create, delete, and manage subscriptions for AWS SNS topics. + - The C(sns_topic) module allows you to create, delete, and manage subscriptions for AWS SNS topics. version_added: 2.0 author: - "Joel Thompson (@joelthompson)" diff --git a/lib/ansible/modules/cloud/lxd/lxd_container.py b/lib/ansible/modules/cloud/lxd/lxd_container.py index 11040cfc04..95851525e0 100644 --- a/lib/ansible/modules/cloud/lxd/lxd_container.py +++ b/lib/ansible/modules/cloud/lxd/lxd_container.py @@ -96,14 +96,14 @@ options: default: 30 wait_for_ipv4_addresses: description: - - If this is true, the M(lxd_container) waits until IPv4 addresses + - If this is true, the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the container after starting or restarting. required: false default: false force_stop: description: - - If this is true, the M(lxd_container) forces to stop the container + - If this is true, the C(lxd_container) forces to stop the container when it stops or restarts the container. required: false default: false diff --git a/lib/ansible/modules/commands/command.py b/lib/ansible/modules/commands/command.py index 73b13e72d1..6f041bc2ce 100644 --- a/lib/ansible/modules/commands/command.py +++ b/lib/ansible/modules/commands/command.py @@ -29,7 +29,7 @@ module: command short_description: Executes a command on a remote node version_added: historical description: - - The M(command) module takes the command name followed by a list of space-delimited arguments. + - The C(command) module takes the command name followed by a list of space-delimited arguments. - The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like C($HOME) and operations like C("<"), C(">"), C("|"), C(";") and C("&") will not work (use the M(shell) @@ -72,7 +72,7 @@ options: required: false 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. - The M(command) module is much more secure as it's not affected by the user's environment. + The C(command) module is much more secure as it's not affected by the user's environment. - " C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this." author: diff --git a/lib/ansible/modules/commands/expect.py b/lib/ansible/modules/commands/expect.py index 9a4327086d..a7d989ba11 100644 --- a/lib/ansible/modules/commands/expect.py +++ b/lib/ansible/modules/commands/expect.py @@ -28,7 +28,7 @@ module: expect version_added: 2.0 short_description: Executes a command and responds to prompts description: - - The M(expect) module executes a command and responds to prompts + - The C(expect) module executes a command and responds to prompts - The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like C($HOME) and operations like C("<"), C(">"), C("|"), and C("&") will not work diff --git a/lib/ansible/modules/commands/raw.py b/lib/ansible/modules/commands/raw.py index 2bf724e77e..041d89b99c 100644 --- a/lib/ansible/modules/commands/raw.py +++ b/lib/ansible/modules/commands/raw.py @@ -44,7 +44,7 @@ description: all core modules require it. Another is speaking to any devices such as routers that do not have any Python installed. In any other case, using the M(shell) or M(command) module is much more appropriate. Arguments - given to M(raw) are run directly through the configured remote shell. + given to C(raw) are run directly through the configured remote shell. Standard output, error output and return code are returned when available. There is no change handler support for this module. - This module does not require python on the remote system, much like diff --git a/lib/ansible/modules/commands/script.py b/lib/ansible/modules/commands/script.py index 16d09a5934..98c3c18d9d 100644 --- a/lib/ansible/modules/commands/script.py +++ b/lib/ansible/modules/commands/script.py @@ -23,7 +23,7 @@ module: script version_added: "0.9" short_description: Runs a local script on a remote node after transferring it description: - - "The M(script) module takes the script name followed by a list of + - "The C(script) module takes the script name followed by a list of space-delimited arguments. " - "The local script at path will be transferred to the remote node and then executed. " - "The given script will be processed through the shell environment on the remote node. " diff --git a/lib/ansible/modules/commands/shell.py b/lib/ansible/modules/commands/shell.py index a29623a5ec..c2f8daa69c 100644 --- a/lib/ansible/modules/commands/shell.py +++ b/lib/ansible/modules/commands/shell.py @@ -26,7 +26,7 @@ DOCUMENTATION = ''' module: shell short_description: Execute commands in nodes. description: - - The M(shell) module takes the command name followed by a list of space-delimited arguments. + - 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 the command through a shell (C(/bin/sh)) on the remote node. version_added: "0.2" @@ -69,8 +69,8 @@ options: 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 - playbooks will follow the trend of using M(command) unless M(shell) is - explicitly required. When running ad-hoc commands, use your best + playbooks will follow the trend of using M(command) unless the C(shell) + module is explicitly required. When running ad-hoc commands, use your best judgement. - 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. diff --git a/lib/ansible/modules/files/archive.py b/lib/ansible/modules/files/archive.py index 0f7a3ae90d..a40928d671 100644 --- a/lib/ansible/modules/files/archive.py +++ b/lib/ansible/modules/files/archive.py @@ -30,7 +30,7 @@ version_added: 2.3 short_description: Creates a compressed archive of one or more files or trees. extends_documentation_fragment: files description: - - The M(archive) module packs an archive. It is the opposite of the unarchive module. By default, it assumes the compression source exists on the target. It will not copy the source file from the local system to the target before archiving. Source files can be deleted after archival by specifying C(remove)=I(True). + - The C(archive) module packs an archive. It is the opposite of the unarchive module. By default, it assumes the compression source exists on the target. It will not copy the source file from the local system to the target before archiving. Source files can be deleted after archival by specifying C(remove)=I(True). options: path: description: diff --git a/lib/ansible/modules/files/assemble.py b/lib/ansible/modules/files/assemble.py index 41e7530e44..b6f1d0329f 100644 --- a/lib/ansible/modules/files/assemble.py +++ b/lib/ansible/modules/files/assemble.py @@ -31,7 +31,7 @@ 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. M(assemble) will take a directory of files that can be + 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). diff --git a/lib/ansible/modules/files/copy.py b/lib/ansible/modules/files/copy.py index 024633ffb8..02a1c74570 100644 --- a/lib/ansible/modules/files/copy.py +++ b/lib/ansible/modules/files/copy.py @@ -28,7 +28,7 @@ module: copy version_added: "historical" short_description: Copies files to remote locations. description: - - The M(copy) module copies a file on the local box to remote locations. Use the M(fetch) module to copy files from remote locations to the local box. If you need variable interpolation in copied files, use the M(template) module. + - The C(copy) module copies a file on the local box to remote locations. Use the M(fetch) module to copy files from remote locations to the local box. If you need variable interpolation in copied files, use the M(template) module. options: src: description: diff --git a/lib/ansible/modules/files/file.py b/lib/ansible/modules/files/file.py index ce722432be..4ec22b5b7a 100644 --- a/lib/ansible/modules/files/file.py +++ b/lib/ansible/modules/files/file.py @@ -31,7 +31,7 @@ extends_documentation_fragment: files description: - Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules support the same options as - the M(file) module - including M(copy), M(template), and M(assemble). + the C(file) module - including M(copy), M(template), and M(assemble). notes: - See also M(copy), M(template), M(assemble) requirements: [ ] @@ -53,7 +53,7 @@ options: or M(template) module if you want that behavior. If C(link), the symbolic link will be created or changed. Use C(hard) for hardlinks. If C(absent), directories will be recursively deleted, and files or symlinks will be unlinked. - Note that M(file) will not fail if the C(path) does not exist as the state did not change. + Note that C(file) will not fail if the C(path) does not exist as the state did not change. If C(touch) (new in 1.4), an empty file will be created if the C(path) does not exist, while an existing file or directory will receive updated file access and modification times (similar to the way `touch` works from the command line). diff --git a/lib/ansible/modules/files/tempfile.py b/lib/ansible/modules/files/tempfile.py index 021c88dbbb..1e4ac0bcd2 100644 --- a/lib/ansible/modules/files/tempfile.py +++ b/lib/ansible/modules/files/tempfile.py @@ -30,7 +30,7 @@ author: - Krzysztof Magosa short_description: Creates temporary files and directories. description: - - The M(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible you need to use M(file) module. + - The C(tempfile) module creates temporary files and directories. C(mktemp) command takes different parameters on various systems, this module helps to avoid troubles related to that. Files/directories created by module are accessible only by creator. In case you need to make them world-accessible you need to use M(file) module. options: state: description: diff --git a/lib/ansible/modules/files/unarchive.py b/lib/ansible/modules/files/unarchive.py index 779be1ee53..8e37e3d80f 100644 --- a/lib/ansible/modules/files/unarchive.py +++ b/lib/ansible/modules/files/unarchive.py @@ -32,7 +32,7 @@ version_added: 1.4 short_description: Unpacks an archive after (optionally) copying it from the local machine. extends_documentation_fragment: files description: - - The M(unarchive) module unpacks an archive. By default, it will copy the source file from the local system to the target before unpacking - set remote_src=yes to unpack an archive which already exists on the target.. + - The C(unarchive) module unpacks an archive. By default, it will copy the source file from the local system to the target before unpacking - set remote_src=yes to unpack an archive which already exists on the target.. options: src: description: diff --git a/lib/ansible/modules/monitoring/nagios.py b/lib/ansible/modules/monitoring/nagios.py index c29df624a4..dd2306dd59 100644 --- a/lib/ansible/modules/monitoring/nagios.py +++ b/lib/ansible/modules/monitoring/nagios.py @@ -24,11 +24,11 @@ DOCUMENTATION = ''' module: nagios short_description: Perform common tasks in Nagios related to downtime and notifications. description: - - "The M(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts." + - "The C(nagios) module has two basic functions: scheduling downtime and toggling alerts for services or hosts." - All actions require the I(host) parameter to be given explicitly. In playbooks you can use the C({{inventory_hostname}}) variable to refer to the host the playbook is currently running on. - You can specify multiple services at once by separating them with commas, .e.g., C(services=httpd,nfs,puppet). - When specifying what service to handle there is a special service value, I(host), which will handle alerts/downtime for the I(host itself), e.g., C(service=host). This keyword may not be given with other services at the same time. I(Setting alerts/downtime for a host does not affect alerts/downtime for any of the services running on it.) To schedule downtime for all services on particular host use keyword "all", e.g., C(service=all). - - When using the M(nagios) module you will need to specify your Nagios server using the C(delegate_to) parameter. + - When using the C(nagios) module you will need to specify your Nagios server using the C(delegate_to) parameter. version_added: "0.7" options: action: diff --git a/lib/ansible/modules/network/asa/asa_command.py b/lib/ansible/modules/network/asa/asa_command.py index 3bffcca042..0dbecf946d 100644 --- a/lib/ansible/modules/network/asa/asa_command.py +++ b/lib/ansible/modules/network/asa/asa_command.py @@ -29,7 +29,7 @@ author: "Peter Sprygada (@privateip), Patrick Ogenstad (@ogenstad)" short_description: Run arbitrary commands on Cisco ASA devices. description: - Sends arbitrary commands to an ASA node and returns the results - read from the device. The M(asa_command) module includes an + read from the device. The C(asa_command) module includes an argument that will cause the module to wait for a specific condition before returning or timing out if the condition is not met. extends_documentation_fragment: asa diff --git a/lib/ansible/modules/network/dellos6/dellos6_command.py b/lib/ansible/modules/network/dellos6/dellos6_command.py index 19efe7e083..dc7e56c51c 100644 --- a/lib/ansible/modules/network/dellos6/dellos6_command.py +++ b/lib/ansible/modules/network/dellos6/dellos6_command.py @@ -31,7 +31,7 @@ version_added: "2.2" short_description: Run commands on remote devices running Dell OS6 description: - Sends arbitrary commands to a Dell OS6 node and returns the results - read from the device. The M(dellos6_command) module includes an + read from the device. The C(dellos6_command) module includes an argument that will cause the module to wait for a specific condition before returning or timing out if the condition is not met. - This module does not support running commands in configuration mode. diff --git a/lib/ansible/modules/network/dellos9/dellos9_config.py b/lib/ansible/modules/network/dellos9/dellos9_config.py index 637f8f792f..f2cc8e0f07 100755 --- a/lib/ansible/modules/network/dellos9/dellos9_config.py +++ b/lib/ansible/modules/network/dellos9/dellos9_config.py @@ -149,7 +149,7 @@ notes: - This module requires to increase the ssh connection rate limit. Use the following command I(ip ssh connection-rate-limit 60) - to configure the same. This can be done via M(dellos9_config) module + to configure the same. This can be done via C(dellos9_config) module as well. """ diff --git a/lib/ansible/modules/network/junos/junos_netconf.py b/lib/ansible/modules/network/junos/junos_netconf.py index 6f47daa8db..11005bdd11 100644 --- a/lib/ansible/modules/network/junos/junos_netconf.py +++ b/lib/ansible/modules/network/junos/junos_netconf.py @@ -45,7 +45,7 @@ options: version_added: "2.2" state: description: - - Specifies the state of the M(junos_netconf) resource on + - Specifies the state of the C(junos_netconf) resource on the remote device. If the I(state) argument is set to I(present) the netconf service will be configured. If the I(state) argument is set to I(absent) the netconf service diff --git a/lib/ansible/modules/network/wakeonlan.py b/lib/ansible/modules/network/wakeonlan.py index 08bd3b5d80..4188fdcf3e 100644 --- a/lib/ansible/modules/network/wakeonlan.py +++ b/lib/ansible/modules/network/wakeonlan.py @@ -28,7 +28,7 @@ module: wakeonlan version_added: 2.2 short_description: Send a magic Wake-on-LAN (WoL) broadcast packet description: - - The M(wakeonlan) module sends magic Wake-on-LAN (WoL) broadcast packets. + - The C(wakeonlan) module sends magic Wake-on-LAN (WoL) broadcast packets. options: mac: description: diff --git a/lib/ansible/modules/notification/grove.py b/lib/ansible/modules/notification/grove.py index fe16289a22..593b8def1f 100644 --- a/lib/ansible/modules/notification/grove.py +++ b/lib/ansible/modules/notification/grove.py @@ -26,7 +26,7 @@ module: grove version_added: 1.4 short_description: Sends a notification to a grove.io channel description: - - The M(grove) module sends a message for a service to a Grove.io + - The C(grove) module sends a message for a service to a Grove.io channel. options: channel_token: diff --git a/lib/ansible/modules/notification/hall.py b/lib/ansible/modules/notification/hall.py index 86e91c5a97..610417b745 100755 --- a/lib/ansible/modules/notification/hall.py +++ b/lib/ansible/modules/notification/hall.py @@ -27,7 +27,7 @@ DOCUMENTATION = """ module: hall short_description: Send notification to Hall description: - - "The M(hall) module connects to the U(https://hall.com) messaging API and allows you to deliver notication messages to rooms." + - "The C(hall) module connects to the U(https://hall.com) messaging API and allows you to deliver notication messages to rooms." version_added: "2.0" author: Billy Kimble (@bkimble) options: diff --git a/lib/ansible/modules/notification/rocketchat.py b/lib/ansible/modules/notification/rocketchat.py index 60f11539ef..035799efdd 100644 --- a/lib/ansible/modules/notification/rocketchat.py +++ b/lib/ansible/modules/notification/rocketchat.py @@ -28,7 +28,7 @@ DOCUMENTATION = """ module: rocketchat short_description: Send notifications to Rocket Chat description: - - The M(rocketchat) module sends notifications to Rocket Chat via the Incoming WebHook integration + - The C(rocketchat) module sends notifications to Rocket Chat via the Incoming WebHook integration version_added: "2.2" author: "Ramon de la Fuente (@ramondelafuente)" options: diff --git a/lib/ansible/modules/notification/slack.py b/lib/ansible/modules/notification/slack.py index 5ea1aedf35..d004c48e40 100644 --- a/lib/ansible/modules/notification/slack.py +++ b/lib/ansible/modules/notification/slack.py @@ -29,7 +29,7 @@ DOCUMENTATION = """ module: slack short_description: Send Slack notifications description: - - The M(slack) module sends notifications to U(http://slack.com) via the Incoming WebHook integration + - The C(slack) module sends notifications to U(http://slack.com) via the Incoming WebHook integration version_added: "1.6" author: "Ramon de la Fuente (@ramondelafuente)" options: diff --git a/lib/ansible/modules/notification/sns.py b/lib/ansible/modules/notification/sns.py index 03a3028e34..7348c6173a 100644 --- a/lib/ansible/modules/notification/sns.py +++ b/lib/ansible/modules/notification/sns.py @@ -26,7 +26,7 @@ DOCUMENTATION = """ module: sns short_description: Send Amazon Simple Notification Service (SNS) messages description: - - The M(sns) module sends notifications to a topic on your Amazon SNS account + - The C(sns) module sends notifications to a topic on your Amazon SNS account version_added: 1.6 author: "Michael J. Schultz (@mjschultz)" options: diff --git a/lib/ansible/modules/packaging/language/easy_install.py b/lib/ansible/modules/packaging/language/easy_install.py index 1f633c6b9d..b1be5798da 100644 --- a/lib/ansible/modules/packaging/language/easy_install.py +++ b/lib/ansible/modules/packaging/language/easy_install.py @@ -79,7 +79,7 @@ options: choices: [present, latest] default: present notes: - - Please note that the M(easy_install) module can only install Python + - Please note that the C(easy_install) module can only install Python libraries. Thus this module is not able to remove libraries. It is generally recommended to use the M(pip) module which you can first install using M(easy_install). diff --git a/lib/ansible/modules/source_control/git_config.py b/lib/ansible/modules/source_control/git_config.py index c9b5974a4f..0117b942b3 100644 --- a/lib/ansible/modules/source_control/git_config.py +++ b/lib/ansible/modules/source_control/git_config.py @@ -33,7 +33,7 @@ version_added: 2.1 requirements: ['git'] short_description: Read and write git configuration description: - - The M(git_config) module changes git configuration by invoking 'git config'. + - The C(git_config) module changes git configuration by invoking 'git config'. This is needed if you don't want to use M(template) for the entire git config file (e.g. because you need to change just C(user.email) in /etc/.git/config). Solutions involving M(command) are cumbersone or diff --git a/lib/ansible/modules/system/known_hosts.py b/lib/ansible/modules/system/known_hosts.py index 5d060ddb08..4397255c5f 100755 --- a/lib/ansible/modules/system/known_hosts.py +++ b/lib/ansible/modules/system/known_hosts.py @@ -27,7 +27,7 @@ DOCUMENTATION = ''' module: known_hosts short_description: Add or remove a host from the C(known_hosts) file description: - - The M(known_hosts) module lets you add or remove a host keys from the C(known_hosts) file. + - The C(known_hosts) module lets you add or remove a host keys from the C(known_hosts) file. - Starting at Ansible 2.2, multiple entries per host are allowed, but only one for each key type supported by ssh. This is useful if you're going to want to use the M(git) module over ssh, for example. - If you have a very large number of host keys to manage, you will find the M(template) module more useful. diff --git a/lib/ansible/modules/system/pam_limits.py b/lib/ansible/modules/system/pam_limits.py index 3e520dc850..2ba934ab8d 100644 --- a/lib/ansible/modules/system/pam_limits.py +++ b/lib/ansible/modules/system/pam_limits.py @@ -30,7 +30,7 @@ authors: - "Sebastien Rohaut (@usawa)" short_description: Modify Linux PAM limits description: - - The M(pam_limits) module modify PAM limits, default in /etc/security/limits.conf. + - The C(pam_limits) module modify PAM limits, default in /etc/security/limits.conf. For the full documentation, see man limits.conf(5). options: domain: diff --git a/lib/ansible/modules/web_infrastructure/jenkins_script.py b/lib/ansible/modules/web_infrastructure/jenkins_script.py index 9b0e64c867..df77d4549c 100644 --- a/lib/ansible/modules/web_infrastructure/jenkins_script.py +++ b/lib/ansible/modules/web_infrastructure/jenkins_script.py @@ -31,7 +31,7 @@ module: jenkins_script short_description: Executes a groovy script in the jenkins instance version_added: '2.3' description: - - The M(jenkins_script) module takes a script plus a dict of values + - The C(jenkins_script) module takes a script plus a dict of values to use within the script and returns the result of the script being run. options: diff --git a/lib/ansible/modules/windows/win_command.py b/lib/ansible/modules/windows/win_command.py index d528137550..6939b93a54 100644 --- a/lib/ansible/modules/windows/win_command.py +++ b/lib/ansible/modules/windows/win_command.py @@ -29,7 +29,7 @@ module: win_command short_description: Executes a command on a remote Windows node version_added: 2.2 description: - - The M(win_command) module takes the command name followed by a list of space-delimited arguments. + - The C(win_command) module takes the command name followed by a list of space-delimited arguments. - The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like C($env:HOME) and operations like C("<"), C(">"), C("|"), and C(";") will not work (use the M(win_shell) @@ -52,7 +52,7 @@ options: notes: - If you want to run a command through a shell (say you are using C(<), C(>), C(|), etc), you actually want the M(win_shell) module instead. The - M(win_command) module is much more secure as it's not affected by the user's + C(win_command) module is much more secure as it's not affected by the user's environment. - " C(creates), C(removes), and C(chdir) can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this." author: diff --git a/lib/ansible/modules/windows/win_copy.py b/lib/ansible/modules/windows/win_copy.py index 64be20a0a1..90a49f03f7 100644 --- a/lib/ansible/modules/windows/win_copy.py +++ b/lib/ansible/modules/windows/win_copy.py @@ -29,7 +29,7 @@ module: win_copy version_added: "1.9.2" short_description: Copies files to remote locations on windows hosts. description: - - The M(win_copy) module copies a file on the local box to remote windows locations. + - The C(win_copy) module copies a file on the local box to remote windows locations. options: src: description: diff --git a/lib/ansible/modules/windows/win_shell.py b/lib/ansible/modules/windows/win_shell.py index 921ddbf4ea..2e6d733f62 100644 --- a/lib/ansible/modules/windows/win_shell.py +++ b/lib/ansible/modules/windows/win_shell.py @@ -29,7 +29,7 @@ module: win_shell short_description: Execute shell commands on target hosts. version_added: 2.2 description: - - The M(win_shell) module takes the command name followed by a list of space-delimited arguments. + - The C(win_shell) module takes the command name followed by a list of space-delimited arguments. It is similar to the M(win_command) module, but runs the command via a shell (defaults to PowerShell) on the target host. options: @@ -53,7 +53,7 @@ options: notes: - If you want to run an executable securely and predictably, it may be better to use the M(win_command) module instead. Best practices when writing - playbooks will follow the trend of using M(win_command) unless M(win_shell) is + playbooks will follow the trend of using M(win_command) unless C(win_shell) is explicitly required. When running ad-hoc commands, use your best judgement. - WinRM will not return from a command execution until all child processes created have exited. Thus, it is not possible to use win_shell to spawn long-running child or background processes. Consider creating a Windows service for managing background processes.