Fix code-blocks to use correct syntax highlighting

docs/docsite/rst/dev_guide/developing_modules.rst

@@ -543,7 +543,7 @@ If you are using Ansible with the :envvar:`ANSIBLE_KEEP_REMOTE_FILES`
 environment variables to keep the remote module file, here's a sample of how
 your debugging session will start:
 
-.. code-block:: sh
+.. code-block:: shell-session
 
     $ ANSIBLE_KEEP_REMOTE_FILES=1 ansible localhost -m ping -a 'data=debugging_session' -vvv
     <127.0.0.1> ESTABLISH LOCAL CONNECTION FOR USER: badger

docs/docsite/rst/dev_guide/developing_test_pr.rst

@@ -180,9 +180,11 @@ If the PR does not resolve the issue, or if you see any failures from the unit/i
    |
    | When I ran this Ubuntu 16.04 it failed with the following:
    |
+   |   ```
    |   BLARG
    |   StrackTrace
    |   RRRARRGGG
+   |   ```
 
 When you are done testing a feature branch, you can remove it with the following command:
 

docs/docsite/rst/playbooks_filters.rst

@@ -453,6 +453,8 @@ It is also possible to fully customize the comment style::
 
 That will create the following output:
 
+.. code-block:: sh
+
 .. code-block:: sh
 
     #######

hacking/templates/rst.j2

@@ -200,5 +200,5 @@ For more information on what this means please read :doc:`modules_extra`
 {% endif %}
 {% endif %}
 
-For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`dev_guide/developing_test_pr` and :doc:`developing_modules`.
+For help in developing on modules, should you be so inclined, please read :doc:`community`, :doc:`dev_guide/developing_test_pr` and :doc:`dev_guide/developing_modules`.
 

lib/ansible/modules/cloud/amazon/cloudformation_facts.py

@@ -87,22 +87,22 @@ EXAMPLES = '''
     stack_policy: true
 
 # Example dictionary outputs for stack_outputs, stack_parameters and stack_resources:
-"stack_outputs": {
+# "stack_outputs": {
-    "ApplicationDatabaseName": "dazvlpr01xj55a.ap-southeast-2.rds.amazonaws.com",
+#     "ApplicationDatabaseName": "dazvlpr01xj55a.ap-southeast-2.rds.amazonaws.com",
-    ...
+#     ...
-},
+# },
-"stack_parameters": {
+# "stack_parameters": {
-    "DatabaseEngine": "mysql",
+#     "DatabaseEngine": "mysql",
-    "DatabasePassword": "****",
+#     "DatabasePassword": "****",
-    ...
+#     ...
-},
+# },
-"stack_resources": {
+# "stack_resources": {
-    "AutoscalingGroup": "dev-someapp-AutoscalingGroup-1SKEXXBCAN0S7",
+#     "AutoscalingGroup": "dev-someapp-AutoscalingGroup-1SKEXXBCAN0S7",
-    "AutoscalingSecurityGroup": "sg-abcd1234",
+#     "AutoscalingSecurityGroup": "sg-abcd1234",
-    "ApplicationDatabase": "dazvlpr01xj55a",
+#     "ApplicationDatabase": "dazvlpr01xj55a",
-    "EcsTaskDefinition": "arn:aws:ecs:ap-southeast-2:123456789:task-definition/dev-someapp-EcsTaskDefinition-1F2VM9QB0I7K9:1"
+#     "EcsTaskDefinition": "arn:aws:ecs:ap-southeast-2:123456789:task-definition/dev-someapp-EcsTaskDefinition-1F2VM9QB0I7K9:1"
-    ...
+#     ...
-}
+# }
 '''
 
 RETURN = '''

lib/ansible/modules/cloud/misc/xenserver_facts.py

@@ -50,12 +50,14 @@ EXAMPLES = '''
   with_items: "{{ xs_vms.keys() }}"
   when: xs_vms[item]['power_state'] == "Running"
 
-TASK: [Print running VMs] ***********************************************************
+# Which will print:
-skipping: [10.13.0.22] => (item=CentOS 4.7 (32-bit))
+#
-ok: [10.13.0.22] => (item=Control domain on host: 10.0.13.22) => {
+# TASK: [Print running VMs] ***********************************************************
-    "item": "Control domain on host: 10.0.13.22",
+# skipping: [10.13.0.22] => (item=CentOS 4.7 (32-bit))
-    "msg": "Control domain on host: 10.0.13.22"
+# ok: [10.13.0.22] => (item=Control domain on host: 10.0.13.22) => {
-}
+#     "item": "Control domain on host: 10.0.13.22",
+#     "msg": "Control domain on host: 10.0.13.22"
+# }
 '''
 
 class XenServerFacts:

lib/ansible/modules/cloud/vmware/vsphere_guest.py

@@ -291,7 +291,7 @@ EXAMPLES = '''
   hw_guest_id: "rhel6_64Guest"
   hw_memtotal_mb: 2048
   hw_name: "centos64Guest"
-  hw_power_status: "POWERED ON",
+  hw_power_status: "POWERED ON"
   hw_processor_count: 2
   hw_product_uuid: "ef50bac8-2845-40ff-81d9-675315501dac"
 

lib/ansible/modules/files/find.py

@@ -121,7 +121,7 @@ options:
 '''
 
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Recursively find /tmp files older than 2 days
 - find:
     paths: "/tmp"
@@ -149,9 +149,11 @@ EXAMPLES = '''
     size: "10m"
 
 # find /var/log files equal or greater than 10 megabytes ending with .old or .log.gz via regex
+# Note that yaml double quotes require escaping backslashes but yaml single
+# quotes do not.
 - find:
     paths: "/var/tmp"
-    patterns: "^.*?\.(?:old|log\.gz)$"
+    patterns: "^.*?\\.(?:old|log\\.gz)$"
     size: "10m"
     use_regex: True
 '''

lib/ansible/modules/files/lineinfile.py

@@ -160,15 +160,16 @@ EXAMPLES = r"""
     line: '192.168.1.99 foo.lab.net foo'
 
 # Fully quoted because of the ': ' on the line. See the Gotchas in the YAML docs.
-- lineinfile: "
+- lineinfile:
     dest: /etc/sudoers
     state: present
-    regexp: '^%wheel'
+    regexp: '^%wheel\s'
     line: '%wheel ALL=(ALL) NOPASSWD: ALL'
 
+# Yaml requires escaping backslashes in double quotes but not in single quotes
 - lineinfile:
     dest: /opt/jboss-as/bin/standalone.conf
-    regexp: '^(.*)Xms(\d+)m(.*)$'
+    regexp: "^(.*)Xms(\\d+)m(.*)$"
     line: '\1Xms${xms}m\3'
     backrefs: yes
 

lib/ansible/modules/messaging/rabbitmq_binding.py

@@ -109,7 +109,7 @@ EXAMPLES = '''
     name: topicExchange
     destination: topicExchange
     type: exchange
-    routing_key: *.info
+    routing_key: '*.info'
 '''
 
 import requests

lib/ansible/modules/network/basics/slurp.py

@@ -48,11 +48,24 @@ author:
 '''
 
 EXAMPLES = '''
-ansible host -m slurp -a 'src=/tmp/xx'
+# Find out what the remote machine's mounts are:
-   host | success >> {
+- slurp:
-      "content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=", 
+    src: /proc/mounts
-      "encoding": "base64"
+  register: mounts
-   }
+
+- debug:
+    msg: "{{ mounts['content'] | b64decode }}"
+
+# From the commandline, find the pid of the remote machine's sshd
+# $ ansible host -m slurp -a 'src=/var/run/sshd.pid'
+# host | SUCCESS => {
+#     "changed": false,
+#     "content": "MjE3OQo=",
+#     "encoding": "base64",
+#     "source": "/var/run/sshd.pid"
+# }
+# $ echo MjE3OQo= | base64 -d
+# 2179
 '''
 
 import base64

lib/ansible/modules/network/nmcli.py

@@ -216,112 +216,113 @@ options:
 '''
 
 EXAMPLES='''
-The following examples are working examples that I have run in the field. I followed follow the structure:
+# These examples are using the following inventory:
-```
+#
-|_/inventory/cloud-hosts
+# ## Directory layout:
-|           /group_vars/openstack-stage.yml
+#
-|           /host_vars/controller-01.openstack.host.com
+# |_/inventory/cloud-hosts
-|           /host_vars/controller-02.openstack.host.com
+# |           /group_vars/openstack-stage.yml
-|_/playbook/library/nmcli.py
+# |           /host_vars/controller-01.openstack.host.com
-|          /playbook-add.yml
+# |           /host_vars/controller-02.openstack.host.com
-|          /playbook-del.yml
+# |_/playbook/library/nmcli.py
-```
+# |          /playbook-add.yml
-
+# |          /playbook-del.yml
-## inventory examples
+# ```
-### groups_vars
+#
-```yml
+# ## inventory examples
----
+# ### groups_vars
-#devops_os_define_network
+# ```yml
-storage_gw: "192.0.2.254"
+# ---
-external_gw: "198.51.100.254"
+# #devops_os_define_network
-tenant_gw: "203.0.113.254"
+# storage_gw: "192.0.2.254"
-
+# external_gw: "198.51.100.254"
-#Team vars
+# tenant_gw: "203.0.113.254"
-nmcli_team:
+#
-  - conn_name: tenant
+# #Team vars
-    ip4: '{{ tenant_ip }}'
+# nmcli_team:
-    gw4: '{{ tenant_gw }}'
+#   - conn_name: tenant
-  - conn_name: external
+#     ip4: '{{ tenant_ip }}'
-    ip4: '{{ external_ip }}'
+#     gw4: '{{ tenant_gw }}'
-    gw4: '{{ external_gw }}'
+#   - conn_name: external
-  - conn_name: storage
+#     ip4: '{{ external_ip }}'
-    ip4: '{{ storage_ip }}'
+#     gw4: '{{ external_gw }}'
-    gw4: '{{ storage_gw }}'
+#   - conn_name: storage
-nmcli_team_slave:
+#     ip4: '{{ storage_ip }}'
-  - conn_name: em1
+#     gw4: '{{ storage_gw }}'
-    ifname: em1
+# nmcli_team_slave:
-    master: tenant
+#   - conn_name: em1
-  - conn_name: em2
+#     ifname: em1
-    ifname: em2
+#     master: tenant
-    master: tenant
+#   - conn_name: em2
-  - conn_name: p2p1
+#     ifname: em2
-    ifname: p2p1
+#     master: tenant
-    master: storage
+#   - conn_name: p2p1
-  - conn_name: p2p2
+#     ifname: p2p1
-    ifname: p2p2
+#     master: storage
-    master: external
+#   - conn_name: p2p2
-
+#     ifname: p2p2
-#bond vars
+#     master: external
-nmcli_bond:
+#
-  - conn_name: tenant
+# #bond vars
-    ip4: '{{ tenant_ip }}'
+# nmcli_bond:
-    gw4: ''
+#   - conn_name: tenant
-    mode: balance-rr
+#     ip4: '{{ tenant_ip }}'
-  - conn_name: external
+#     gw4: ''
-    ip4: '{{ external_ip }}'
+#     mode: balance-rr
-    gw4: ''
+#   - conn_name: external
-    mode: balance-rr
+#     ip4: '{{ external_ip }}'
-  - conn_name: storage
+#     gw4: ''
-    ip4: '{{ storage_ip }}'
+#     mode: balance-rr
-    gw4: '{{ storage_gw }}'
+#   - conn_name: storage
-    mode: balance-rr
+#     ip4: '{{ storage_ip }}'
-nmcli_bond_slave:
+#     gw4: '{{ storage_gw }}'
-  - conn_name: em1
+#     mode: balance-rr
-    ifname: em1
+# nmcli_bond_slave:
-    master: tenant
+#   - conn_name: em1
-  - conn_name: em2
+#     ifname: em1
-    ifname: em2
+#     master: tenant
-    master: tenant
+#   - conn_name: em2
-  - conn_name: p2p1
+#     ifname: em2
-    ifname: p2p1
+#     master: tenant
-    master: storage
+#   - conn_name: p2p1
-  - conn_name: p2p2
+#     ifname: p2p1
-    ifname: p2p2
+#     master: storage
-    master: external
+#   - conn_name: p2p2
-
+#     ifname: p2p2
-#ethernet vars
+#     master: external
-nmcli_ethernet:
+#
-  - conn_name: em1
+# #ethernet vars
-    ifname: em1
+# nmcli_ethernet:
-    ip4: '{{ tenant_ip }}'
+#   - conn_name: em1
-    gw4: '{{ tenant_gw }}'
+#     ifname: em1
-  - conn_name: em2
+#     ip4: '{{ tenant_ip }}'
-    ifname: em2
+#     gw4: '{{ tenant_gw }}'
-    ip4: '{{ tenant_ip1 }}'
+#   - conn_name: em2
-    gw4: '{{ tenant_gw }}'
+#     ifname: em2
-  - conn_name: p2p1
+#     ip4: '{{ tenant_ip1 }}'
-    ifname: p2p1
+#     gw4: '{{ tenant_gw }}'
-    ip4: '{{ storage_ip }}'
+#   - conn_name: p2p1
-    gw4: '{{ storage_gw }}'
+#     ifname: p2p1
-  - conn_name: p2p2
+#     ip4: '{{ storage_ip }}'
-    ifname: p2p2
+#     gw4: '{{ storage_gw }}'
-    ip4: '{{ external_ip }}'
+#   - conn_name: p2p2
-    gw4: '{{ external_gw }}'
+#     ifname: p2p2
-```
+#     ip4: '{{ external_ip }}'
-
+#     gw4: '{{ external_gw }}'
-### host_vars
+# ```
-```yml
+#
----
+# ### host_vars
-storage_ip: "192.0.2.91/23"
+# ```yml
-external_ip: "198.51.100.23/21"
+# ---
-tenant_ip: "203.0.113.77/23"
+# storage_ip: "192.0.2.91/23"
-```
+# external_ip: "198.51.100.23/21"
+# tenant_ip: "203.0.113.77/23"
+# ```
 
 
 
 ## playbook-add.yml example
 
-```yml
 ---
 - hosts: openstack-stage
   remote_user: root
@@ -360,42 +361,40 @@ tenant_ip: "203.0.113.77/23"
       - '{{ nmcli_team_slave }}'
 
 ###### Working with all cloud nodes - Bonding
-#  - name: try nmcli add bond - conn_name only & ip4 gw4 mode
+ - name: try nmcli add bond - conn_name only & ip4 gw4 mode
-#    nmcli:
+   nmcli:
-#      type: bond
+     type: bond
-#      conn_name: '{{ item.conn_name }}'
+     conn_name: '{{ item.conn_name }}'
-#      ip4: '{{ item.ip4 }}'
+     ip4: '{{ item.ip4 }}'
-#      gw4: '{{ item.gw4 }}'
+     gw4: '{{ item.gw4 }}'
-#      mode: '{{ item.mode }}'
+     mode: '{{ item.mode }}'
-#      state: present
+     state: present
-#    with_items:
+   with_items:
-#      - '{{ nmcli_bond }}'
+     - '{{ nmcli_bond }}'
-#
+
-#  - name: try nmcli add bond-slave
+ - name: try nmcli add bond-slave
-#    nmcli:
+   nmcli:
-#      type: bond-slave
+     type: bond-slave
-#      conn_name: '{{ item.conn_name }}'
+     conn_name: '{{ item.conn_name }}'
-#      ifname: '{{ item.ifname }}'
+     ifname: '{{ item.ifname }}'
-#      master: '{{ item.master }}'
+     master: '{{ item.master }}'
-#      state: present
+     state: present
-#    with_items:
+   with_items:
-#      - '{{ nmcli_bond_slave }}'
+     - '{{ nmcli_bond_slave }}'
 
 ##### Working with all cloud nodes - Ethernet
-#  - name: nmcli add Ethernet - conn_name only & ip4 gw4
+  - name: nmcli add Ethernet - conn_name only & ip4 gw4
-#    nmcli:
+    nmcli:
-#      type: ethernet
+      type: ethernet
-#      conn_name: '{{ item.conn_name }}'
+      conn_name: '{{ item.conn_name }}'
-#      ip4: '{{ item.ip4 }}'
+      ip4: '{{ item.ip4 }}'
-#      gw4: '{{ item.gw4 }}'
+      gw4: '{{ item.gw4 }}'
-#      state: present
+      state: present
-#    with_items:
+    with_items:
-#      - '{{ nmcli_ethernet }}'
+      - '{{ nmcli_ethernet }}'
-```
 
 ## playbook-del.yml example
 
-```yml
 ---
 - hosts: openstack-stage
   remote_user: root
@@ -421,7 +420,7 @@ tenant_ip: "203.0.113.77/23"
       - conn_name: team-p1p2
       - conn_name: team-p2p1
       - conn_name: team-p2p2
-```
+
 # To add an Ethernet connection with static IP configuration, issue a command as follows
 - nmcli:
     conn_name: my-eth1
@@ -464,7 +463,7 @@ tenant_ip: "203.0.113.77/23"
 - nmcli:
     ctype: ethernet
     name: my-eth1
-    ifname: *
+    ifname: '*'
     state: present
 
 # To change the property of a setting e.g. MTU, issue a command as follows:
@@ -474,20 +473,20 @@ tenant_ip: "203.0.113.77/23"
     type: ethernet
     state: present
 
-    Exit Status's:
+# Exit Status's:
-        - nmcli exits with status 0 if it succeeds, a value greater than 0 is
+#     - nmcli exits with status 0 if it succeeds, a value greater than 0 is
-        returned if an error occurs.
+#     returned if an error occurs.
-        - 0 Success - indicates the operation succeeded
+#     - 0 Success - indicates the operation succeeded
-        - 1 Unknown or unspecified error
+#     - 1 Unknown or unspecified error
-        - 2 Invalid user input, wrong nmcli invocation
+#     - 2 Invalid user input, wrong nmcli invocation
-        - 3 Timeout expired (see --wait option)
+#     - 3 Timeout expired (see --wait option)
-        - 4 Connection activation failed
+#     - 4 Connection activation failed
-        - 5 Connection deactivation failed
+#     - 5 Connection deactivation failed
-        - 6 Disconnecting device failed
+#     - 6 Disconnecting device failed
-        - 7 Connection deletion failed
+#     - 7 Connection deletion failed
-        - 8 NetworkManager is not running
+#     - 8 NetworkManager is not running
-        - 9 nmcli and NetworkManager versions mismatch
+#     - 9 nmcli and NetworkManager versions mismatch
-        - 10 Connection, device, or access point does not exist.
+#     - 10 Connection, device, or access point does not exist.
 '''
 # import ansible.module_utils.basic
 import os

lib/ansible/modules/packaging/os/dnf.py

@@ -124,7 +124,7 @@ EXAMPLES = '''
 
 - name: upgrade all packages
   dnf:
-    name: *
+    name: "*"
     state: latest
 
 - name: install the nginx rpm from a remote repo

lib/ansible/modules/packaging/os/openbsd_pkg.py

@@ -126,7 +126,7 @@ EXAMPLES = '''
 
 # Update all packages on the system
 - openbsd_pkg:
-    name: *
+    name: '*'
     state: latest
 
 # Purge a package and it's configuration files

lib/ansible/modules/packaging/os/portage.py

@@ -208,12 +208,12 @@ EXAMPLES = '''
 
 # Re-install world from binary packages only and do not allow any compiling
 - portage:
-    package: @world
+    package: '@world'
     usepkgonly: yes
 
 # Sync repositories and update world
 - portage:
-    package: @world
+    package: '@world'
     update: yes
     deep: yes
     sync: yes

lib/ansible/modules/packaging/os/zypper.py

@@ -150,12 +150,12 @@ EXAMPLES = '''
 
 # Update all packages
 - zypper:
-    name: *
+    name: '*'
     state: latest
 
 # Apply all available patches
 - zypper:
-    name: *
+    name: '*'
     state: latest
     type: patch
 

lib/ansible/modules/packaging/os/zypper_repository.py

@@ -135,7 +135,7 @@ EXAMPLES = '''
 
 # Refresh all repos
 - zypper_repository:
-    repo: *
+    repo: '*'
     runrefresh: yes
 
 # Add a repo and add it's gpg key

lib/ansible/modules/system/pam_limits.py

@@ -110,7 +110,7 @@ EXAMPLES = '''
 # Add or modify memlock, both soft and hard, limit for the user james with a comment.
 - pam_limits:
     domain: james
-    limit_type: -
+    limit_type: '-'
     limit_item: memlock
     value: unlimited
     comment: unlimited memory lock for james

lib/ansible/modules/windows/win_iis_website.py

@@ -99,34 +99,8 @@ author: Henrik Wallström
 '''
 
 EXAMPLES = '''
-# This return information about an existing host
-$ ansible -i vagrant-inventory -m win_iis_website -a "name='Default Web Site'" window
-host | success >> {
-    "changed": false,
-    "site": {
-        "ApplicationPool": "DefaultAppPool",
-        "Bindings": [
-            "*:80:"
-        ],
-        "ID": 1,
-        "Name": "Default Web Site",
-        "PhysicalPath": "%SystemDrive%\\inetpub\\wwwroot",
-        "State": "Stopped"
-    }
-}
 
-# This stops an existing site.
+# Start a website
-$ ansible -i hosts -m win_iis_website -a "name='Default Web Site' state=stopped" host
-
-# This creates a new site.
-$ ansible -i hosts -m win_iis_website -a "name=acme physical_path=c:\\sites\\acme" host
-
-# Change logfile .
-$ ansible -i hosts -m win_iis_website -a "name=acme physical_path=c:\\sites\\acme" host
-
-
-# Playbook example
----
 
 - name: Acme IIS site
   win_iis_website:
@@ -140,4 +114,30 @@ $ ansible -i hosts -m win_iis_website -a "name=acme physical_path=c:\\sites\\acm
     parameters: 'logfile.directory:c:\\sites\\logs'
   register: website
 
+# Some commandline examples:
+
+# This return information about an existing host
+# $ ansible -i vagrant-inventory -m win_iis_website -a "name='Default Web Site'" window
+# host | success >> {
+#     "changed": false,
+#     "site": {
+#         "ApplicationPool": "DefaultAppPool",
+#         "Bindings": [
+#             "*:80:"
+#         ],
+#         "ID": 1,
+#         "Name": "Default Web Site",
+#         "PhysicalPath": "%SystemDrive%\\inetpub\\wwwroot",
+#         "State": "Stopped"
+#     }
+# }
+
+# This stops an existing site.
+# $ ansible -i hosts -m win_iis_website -a "name='Default Web Site' state=stopped" host
+
+# This creates a new site.
+# $ ansible -i hosts -m win_iis_website -a "name=acme physical_path=c:\\sites\\acme" host
+
+# Change logfile.
+# $ ansible -i hosts -m win_iis_website -a "name=acme physical_path=c:\\sites\\acme" host
 '''

lib/ansible/modules/windows/win_unzip.py

@@ -71,16 +71,16 @@ author: Phil Schwartz
 
 EXAMPLES = r'''
 # This unzips a library that was downloaded with win_get_url, and removes the file after extraction
-$ ansible -i hosts -m win_unzip -a "src=C:\LibraryToUnzip.zip dest=C:\Lib rm=true" all
+# $ ansible -i hosts -m win_unzip -a "src=C:\\LibraryToUnzip.zip dest=C:\\Lib rm=true" all
 # Playbook example
 
 # Simple unzip
 ---
 - name: Unzip a bz2 (BZip) file
   win_unzip:
-    src: "C:\Users\Phil\Logs.bz2"
+    src: C:\Users\Phil\Logs.bz2
-    dest: "C:\Users\Phil\OldLogs"
+    dest: C:\Users\Phil\OldLogs
-    creates: "C:\Users\Phil\OldLogs"
+    creates: C:\Users\Phil\OldLogs
 
 # This playbook example unzips a .zip file and recursively decompresses the contained .gz files and removes all unneeded compressed files after completion.
 ---