Fix Ansible documentation in part of example formatting. Part 2 (#333)

* Fix Ansible documentation in part of example formatting

* fix

* Revert osx_defaults.py

plugins/modules/packaging/os/apk.py

@@ -58,63 +58,63 @@ notes:
 '''
 
 EXAMPLES = '''
-# Update repositories and install "foo" package
-- apk:
+- name: Update repositories and install foo package
+  apk:
     name: foo
     update_cache: yes
 
-# Update repositories and install "foo" and "bar" packages
-- apk:
+- name: Update repositories and install foo and bar packages
+  apk:
     name: foo,bar
     update_cache: yes
 
-# Remove "foo" package
-- apk:
+- name: Remove foo package
+  apk:
     name: foo
     state: absent
 
-# Remove "foo" and "bar" packages
-- apk:
+- name: Remove foo and bar packages
+  apk:
     name: foo,bar
     state: absent
 
-# Install the package "foo"
-- apk:
+- name: Install the package foo
+  apk:
     name: foo
     state: present
 
-# Install the packages "foo" and "bar"
-- apk:
+- name: Install the packages foo and bar
+  apk:
     name: foo,bar
     state: present
 
-# Update repositories and update package "foo" to latest version
-- apk:
+- name: Update repositories and update package foo to latest version
+  apk:
     name: foo
     state: latest
     update_cache: yes
 
-# Update repositories and update packages "foo" and "bar" to latest versions
-- apk:
+- name: Update repositories and update packages foo and bar to latest versions
+  apk:
     name: foo,bar
     state: latest
     update_cache: yes
 
-# Update all installed packages to the latest versions
-- apk:
+- name: Update all installed packages to the latest versions
+  apk:
     upgrade: yes
 
-# Upgrade / replace / downgrade / uninstall all installed packages to the latest versions available
-- apk:
+- name: Upgrade / replace / downgrade / uninstall all installed packages to the latest versions available
+  apk:
     available: yes
     upgrade: yes
 
-# Update repositories as a separate step
-- apk:
+- name: Update repositories as a separate step
+  apk:
     update_cache: yes
 
-# Install package from a specific repository
-- apk:
+- name: Install package from a specific repository
+  apk:
     name: foo
     state: latest
     update_cache: yes

plugins/modules/packaging/os/homebrew_tap.py

@@ -49,18 +49,22 @@ requirements: [ homebrew ]
 '''
 
 EXAMPLES = '''
-- homebrew_tap:
+- name: Tap a Homebrew repository, state present
+  homebrew_tap:
     name: homebrew/dupes
 
-- homebrew_tap:
+- name: Tap a Homebrew repository, state absent
+  homebrew_tap:
     name: homebrew/dupes
     state: absent
 
-- homebrew_tap:
+- name: Tap a Homebrew repository, state present
+  homebrew_tap:
     name: homebrew/dupes,homebrew/science
     state: present
 
-- homebrew_tap:
+- name: Tap a Homebrew repository using url, state present
+  homebrew_tap:
     name: telemachus/brew
     url: 'https://bitbucket.org/telemachus/brew'
 '''

plugins/modules/packaging/os/layman.py

@@ -46,28 +46,28 @@ options:
 '''
 
 EXAMPLES = '''
-# Install the overlay 'mozilla' which is on the central overlays list.
-- layman:
+- name: Install the overlay mozilla which is on the central overlays list
+  layman:
     name: mozilla
 
-# Install the overlay 'cvut' from the specified alternative list.
-- layman:
+- name: Install the overlay cvut from the specified alternative list
+  layman:
     name: cvut
     list_url: 'http://raw.github.com/cvut/gentoo-overlay/master/overlay.xml'
 
-# Update (sync) the overlay 'cvut', or install if not installed yet.
-- layman:
+- name: Update (sync) the overlay cvut or install if not installed yet
+  layman:
     name: cvut
     list_url: 'http://raw.github.com/cvut/gentoo-overlay/master/overlay.xml'
     state: updated
 
-# Update (sync) all of the installed overlays.
-- layman:
+- name: Update (sync) all of the installed overlays
+  layman:
     name: ALL
     state: updated
 
-# Uninstall the overlay 'cvut'.
-- layman:
+- name: Uninstall the overlay cvut
+  layman:
     name: cvut
     state: absent
 '''

plugins/modules/packaging/os/opkg.py

@@ -53,24 +53,29 @@ requirements:
     - python
 '''
 EXAMPLES = '''
-- opkg:
+- name: Install foo
+  opkg:
     name: foo
     state: present
 
-- opkg:
+- name: Update cache and install foo
+  opkg:
     name: foo
     state: present
     update_cache: yes
 
-- opkg:
+- name: Remove foo
+  opkg:
     name: foo
     state: absent
 
-- opkg:
+- name: Remove foo and bar
+  opkg:
     name: foo,bar
     state: absent
 
-- opkg:
+- name: Install foo using overwrite option forcibly
+  opkg:
     name: foo
     state: present
     force: overwrite

plugins/modules/packaging/os/pkg5_publisher.py

@@ -48,14 +48,14 @@ options:
       - Multiple values may be provided.
 '''
 EXAMPLES = '''
-# Fetch packages for the solaris publisher direct from Oracle:
-- pkg5_publisher:
+- name: Fetch packages for the solaris publisher direct from Oracle
+  pkg5_publisher:
     name: solaris
     sticky: true
     origin: https://pkg.oracle.com/solaris/support/
 
-# Configure a publisher for locally-produced packages:
-- pkg5_publisher:
+- name: Configure a publisher for locally-produced packages
+  pkg5_publisher:
     name: site
     origin: 'https://pkg.example.com/site/'
 '''

plugins/modules/packaging/os/pkgin.py

@@ -68,45 +68,45 @@ options:
 '''
 
 EXAMPLES = '''
-# install package foo
-- pkgin:
+- name: Install package foo
+  pkgin:
     name: foo
     state: present
 
-# Update database and install "foo" package
-- pkgin:
+- name: Update cache and install foo package
+  pkgin:
     name: foo
     update_cache: yes
 
-# remove package foo
-- pkgin:
+- name: Remove package foo
+  pkgin:
     name: foo
     state: absent
 
-# remove packages foo and bar
-- pkgin:
+- name: Remove packages foo and bar
+  pkgin:
     name: foo,bar
     state: absent
 
-# Update repositories as a separate step
-- pkgin:
+- name: Update repositories as a separate step
+  pkgin:
     update_cache: yes
 
-# Upgrade main packages (equivalent to C(pkgin upgrade))
-- pkgin:
+- name: Upgrade main packages (equivalent to pkgin upgrade)
+  pkgin:
     upgrade: yes
 
-# Upgrade all packages (equivalent to C(pkgin full-upgrade))
-- pkgin:
+- name: Upgrade all packages (equivalent to pkgin full-upgrade)
+  pkgin:
     full_upgrade: yes
 
-# Force-upgrade all packages (equivalent to C(pkgin -F full-upgrade))
-- pkgin:
+- name: Force-upgrade all packages (equivalent to pkgin -F full-upgrade)
+  pkgin:
     full_upgrade: yes
     force: yes
 
-# clean packages cache (equivalent to C(pkgin clean))
-- pkgin:
+- name: Clean packages cache (equivalent to pkgin clean)
+  pkgin:
     clean: yes
 '''
 

plugins/modules/packaging/os/pkgutil.py

@@ -48,13 +48,13 @@ options:
 '''
 
 EXAMPLES = '''
-# Install a package
-- pkgutil:
+- name: Install a package
+  pkgutil:
     name: CSWcommon
     state: present
 
-# Install a package from a specific repository
-- pkgutil:
+- name: Install a package from a specific repository
+  pkgutil:
     name: CSWnrpe
     site: 'ftp://myinternal.repo/opencsw/kiel'
     state: latest

plugins/modules/packaging/os/portage.py

@@ -164,44 +164,44 @@ author:
 '''
 
 EXAMPLES = '''
-# Make sure package foo is installed
-- portage:
+- name: Make sure package foo is installed
+  portage:
     package: foo
     state: present
 
-# Make sure package foo is not installed
-- portage:
+- name: Make sure package foo is not installed
+  portage:
     package: foo
     state: absent
 
-# Update package foo to the "latest" version ( os specific alternative to latest )
-- portage:
+- name: Update package foo to the latest version (os specific alternative to latest)
+  portage:
     package: foo
     update: yes
 
-# Install package foo using PORTAGE_BINHOST setup
-- portage:
+- name: Install package foo using PORTAGE_BINHOST setup
+  portage:
     package: foo
     getbinpkg: yes
 
-# Re-install world from binary packages only and do not allow any compiling
-- portage:
+- name: Re-install world from binary packages only and do not allow any compiling
+  portage:
     package: '@world'
     usepkgonly: yes
 
-# Sync repositories and update world
-- portage:
+- name: Sync repositories and update world
+  portage:
     package: '@world'
     update: yes
     deep: yes
     sync: yes
 
-# Remove unneeded packages
-- portage:
+- name: Remove unneeded packages
+  portage:
     depclean: yes
 
-# Remove package foo if it is not explicitly needed
-- portage:
+- name: Remove package foo if it is not explicitly needed
+  portage:
     package: foo
     state: absent
     depclean: yes

plugins/modules/packaging/os/portinstall.py

@@ -38,18 +38,18 @@ author: "berenddeboer (@berenddeboer)"
 '''
 
 EXAMPLES = '''
-# Install package foo
-- portinstall:
+- name: Install package foo
+  portinstall:
     name: foo
     state: present
 
-# Install package security/cyrus-sasl2-saslauthd
-- portinstall:
+- name: Install package security/cyrus-sasl2-saslauthd
+  portinstall:
     name: security/cyrus-sasl2-saslauthd
     state: present
 
-# Remove packages foo and bar
-- portinstall:
+- name: Remove packages foo and bar
+  portinstall:
     name: foo,bar
     state: absent
 '''

plugins/modules/packaging/os/rhn_channel.py

@@ -53,7 +53,8 @@ options:
 '''
 
 EXAMPLES = '''
-- rhn_channel:
+- name: Add a Red Hat software channel
+  rhn_channel:
     name: rhel-x86_64-server-v2vwin-6
     sysname: server01
     url: https://rhn.redhat.com/rpc/api

plugins/modules/packaging/os/slackpkg.py

@@ -46,18 +46,18 @@ requirements: [ "Slackware >= 12.2" ]
 '''
 
 EXAMPLES = '''
-# Install package foo
-- slackpkg:
+- name: Install package foo
+  slackpkg:
     name: foo
     state: present
 
-# Remove packages foo and bar
-- slackpkg:
+- name: Remove packages foo and bar
+  slackpkg:
     name: foo,bar
     state: absent
 
-# Make sure that it is the most updated package
-- slackpkg:
+- name: Make sure that it is the most updated package
+  slackpkg:
     name: foo
     state: latest
 '''

plugins/modules/packaging/os/sorcery.py

@@ -74,36 +74,36 @@ options:
 
 
 EXAMPLES = '''
-# Make sure spell 'foo' is installed
-- sorcery:
+- name: Make sure spell foo is installed
+  sorcery:
     spell: foo
     state: present
 
-# Make sure spells 'foo', 'bar' and 'baz' are removed
-- sorcery:
+- name: Make sure spells foo, bar and baz are removed
+  sorcery:
     spell: foo,bar,baz
     state: absent
 
-# Make sure spell 'foo' with dependencies 'bar' and 'baz' is installed
-- sorcery:
+- name: Make sure spell foo with dependencies bar and baz is installed
+  sorcery:
     spell: foo
     depends: bar,baz
     state: present
 
-# Make sure spell 'foo' with 'bar' and without 'baz' dependencies is installed
-- sorcery:
+- name: Make sure spell foo with bar and without baz dependencies is installed
+  sorcery:
     spell: foo
     depends: +bar,-baz
     state: present
 
-# Make sure spell 'foo' with libressl (providing SSL) dependency is installed
-- sorcery:
+- name: Make sure spell foo with libressl (providing SSL) dependency is installed
+  sorcery:
     spell: foo
     depends: libressl(SSL)
     state: present
 
-# Playbook: make sure spells with/without required dependencies (if any) are installed
-- sorcery:
+- name: Make sure spells with/without required dependencies (if any) are installed
+  sorcery:
     name: "{{ item.spell }}"
     depends: "{{ item.depends | default(None) }}"
     state: present
@@ -112,30 +112,30 @@ EXAMPLES = '''
     - { spell: 'fwknop', depends: 'gpgme' }
     - { spell: 'pv,tnftp,tor' }
 
-# Install the latest version of spell 'foo' using regular glossary
-- sorcery:
+- name: Install the latest version of spell foo using regular glossary
+  sorcery:
     name: foo
     state: latest
 
-# Rebuild spell 'foo'
-- sorcery:
+- name: Rebuild spell foo
+  sorcery:
     spell: foo
     state: rebuild
 
-# Rebuild the whole system, but update Sorcery and Codex first
-- sorcery:
+- name: Rebuild the whole system, but update Sorcery and Codex first
+  sorcery:
     spell: '*'
     state: rebuild
     update: yes
     update_cache: yes
 
-# Refresh the grimoire collection if it's 1 day old using native sorcerous alias
-- sorcery:
+- name: Refresh the grimoire collection if it is 1 day old using native sorcerous alias
+  sorcery:
     update_codex: yes
     cache_valid_time: 86400
 
-# Update only Sorcery itself
-- sorcery:
+- name: Update only Sorcery itself
+  sorcery:
     update: yes
 '''
 

plugins/modules/packaging/os/svr4pkg.py

@@ -61,33 +61,33 @@ options:
 '''
 
 EXAMPLES = '''
-# Install a package from an already copied file
-- svr4pkg:
+- name: Install a package from an already copied file
+  svr4pkg:
     name: CSWcommon
     src: /tmp/cswpkgs.pkg
     state: present
 
-# Install a package directly from an http site
-- svr4pkg:
+- name: Install a package directly from an http site
+  svr4pkg:
     name: CSWpkgutil
     src: 'http://get.opencsw.org/now'
     state: present
     zone: current
 
-# Install a package with a response file
-- svr4pkg:
+- name: Install a package with a response file
+  svr4pkg:
     name: CSWggrep
     src: /tmp/third-party.pkg
     response_file: /tmp/ggrep.response
     state: present
 
-# Ensure that a package is not installed.
-- svr4pkg:
+- name: Ensure that a package is not installed
+  svr4pkg:
     name: SUNWgnome-sound-recorder
     state: absent
 
-# Ensure that a category is not installed.
-- svr4pkg:
+- name: Ensure that a category is not installed
+  svr4pkg:
     name: FIREFOX
     state: absent
     category: true

plugins/modules/packaging/os/swdepot.py

@@ -35,17 +35,20 @@ options:
 '''
 
 EXAMPLES = '''
-- swdepot:
+- name: Install a package
+  swdepot:
     name: unzip-6.0
     state: present
     depot: 'repository:/path'
 
-- swdepot:
+- name: Install the latest version of a package
+  swdepot:
     name: unzip
     state: latest
     depot: 'repository:/path'
 
-- swdepot:
+- name: Remove a package
+  swdepot:
     name: unzip
     state: absent
 '''

plugins/modules/remote_management/hpilo/hpilo_info.py

@@ -46,8 +46,8 @@ notes:
 '''
 
 EXAMPLES = r'''
-# Task to gather facts from a HP iLO interface only if the system is an HP server
-- hpilo_info:
+- name: Gather facts from a HP iLO interface only if the system is an HP server
+  hpilo_info:
     host: YOUR_ILO_ADDRESS
     login: YOUR_ILO_LOGIN
     password: YOUR_ILO_PASSWORD

plugins/modules/remote_management/ipmi/ipmi_boot.py

@@ -88,15 +88,15 @@ uefimode:
 '''
 
 EXAMPLES = '''
-# Ensure bootdevice is HD.
-- ipmi_boot:
+- name: Ensure bootdevice is HD
+  ipmi_boot:
     name: test.testdomain.com
     user: admin
     password: password
     bootdev: hd
 
-# Ensure bootdevice is not Network
-- ipmi_boot:
+- name: Ensure bootdevice is not Network
+  ipmi_boot:
     name: test.testdomain.com
     user: admin
     password: password

plugins/modules/remote_management/ipmi/ipmi_power.py

@@ -60,8 +60,8 @@ powerstate:
 '''
 
 EXAMPLES = '''
-# Ensure machine is powered on.
-- ipmi_power:
+- name: Ensure machine is powered on
+  ipmi_power:
     name: test.testdomain.com
     user: admin
     password: password

plugins/modules/source_control/bzr.py

@@ -45,8 +45,8 @@ options:
 '''
 
 EXAMPLES = '''
-# Example bzr checkout from Ansible Playbooks
-- bzr:
+- name: Checkout
+  bzr:
     name: bzr+ssh://foosball.example.org/path/to/branch
     dest: /srv/checkout
     version: 22

plugins/modules/source_control/git_config.py

@@ -59,70 +59,73 @@ options:
 '''
 
 EXAMPLES = '''
-# Set some settings in ~/.gitconfig
-- git_config:
+- name: Add a setting to ~/.gitconfig
+  git_config:
     name: alias.ci
     scope: global
     value: commit
 
-- git_config:
+- name: Add a setting to ~/.gitconfig
+  git_config:
     name: alias.st
     scope: global
     value: status
 
-# Unset some settings in ~/.gitconfig
-- git_config:
+- name: Remove a setting from ~/.gitconfig
+  git_config:
     name: alias.ci
     scope: global
     state: absent
 
-# Or system-wide:
-- git_config:
-    name: alias.remotev
-    scope: system
-    value: remote -v
-
-- git_config:
+- name: Add a setting to ~/.gitconfig
+  git_config:
     name: core.editor
     scope: global
     value: vim
 
-# scope=system is the default
-- git_config:
+- name: Add a setting system-wide
+  git_config:
+    name: alias.remotev
+    scope: system
+    value: remote -v
+
+- name: Add a setting to a system scope (default)
+  git_config:
     name: alias.diffc
     value: diff --cached
 
-- git_config:
+- name: Add a setting to a system scope (default)
+  git_config:
     name: color.ui
     value: auto
 
-# Make etckeeper not complain when invoked by cron
-- git_config:
+- name: Make etckeeper not complaining when it is invoked by cron
+  git_config:
     name: user.email
     repo: /etc
     scope: local
     value: 'root@{{ ansible_fqdn }}'
 
-# Read individual values from git config
-- git_config:
+- name: Read individual values from git config
+  git_config:
     name: alias.ci
     scope: global
 
-# scope: system is also assumed when reading values, unless list_all=yes
-- git_config:
+- name: Scope system is also assumed when reading values, unless list_all=yes
+  git_config:
     name: alias.diffc
 
-# Read all values from git config
-- git_config:
+- name: Read all values from git config
+  git_config:
     list_all: yes
     scope: global
 
-# When list_all=yes and no scope is specified, you get configuration from all scopes
-- git_config:
+- name: When list_all is yes and no scope is specified, you get configuration from all scopes
+  git_config:
     list_all: yes
 
-# Specify a repository to include local settings
-- git_config:
+- name: Specify a repository to include local settings
+  git_config:
     list_all: yes
     repo: /path/to/repo.git
 '''

plugins/modules/source_control/github/github_deploy_key.py

@@ -75,8 +75,8 @@ notes:
 '''
 
 EXAMPLES = '''
-# add a new read-only deploy key to a GitHub repository using basic authentication
-- github_deploy_key:
+- name: Add a new read-only deploy key to a GitHub repository using basic authentication
+  github_deploy_key:
     owner: "johndoe"
     repo: "example"
     name: "new-deploy-key"
@@ -85,8 +85,8 @@ EXAMPLES = '''
     username: "johndoe"
     password: "supersecretpassword"
 
-# remove an existing deploy key from a GitHub repository
-- github_deploy_key:
+- name: Remove an existing deploy key from a GitHub repository
+  github_deploy_key:
     owner: "johndoe"
     repository: "example"
     name: "new-deploy-key"
@@ -96,8 +96,8 @@ EXAMPLES = '''
     password: "supersecretpassword"
     state: absent
 
-# add a new deploy key to a GitHub repository, replace an existing key, use an OAuth2 token to authenticate
-- github_deploy_key:
+- name: Add a new deploy key to a GitHub repository, replace an existing key, use an OAuth2 token to authenticate
+  github_deploy_key:
     owner: "johndoe"
     repository: "example"
     name: "new-deploy-key"
@@ -105,8 +105,8 @@ EXAMPLES = '''
     force: yes
     token: "ABAQDAwXxn7kIMNWzcDfo..."
 
-# re-add a deploy key to a GitHub repository but with a different name
-- github_deploy_key:
+- name: Re-add a deploy key to a GitHub repository but with a different name
+  github_deploy_key:
     owner: "johndoe"
     repository: "example"
     name: "replace-deploy-key"
@@ -114,8 +114,8 @@ EXAMPLES = '''
     username: "johndoe"
     password: "supersecretpassword"
 
-# add a new deploy key to a GitHub repository using 2FA
-- github_deploy_key:
+- name: Add a new deploy key to a GitHub repository using 2FA
+  github_deploy_key:
     owner: "johndoe"
     repo: "example"
     name: "new-deploy-key-2"
@@ -124,8 +124,8 @@ EXAMPLES = '''
     password: "supersecretpassword"
     otp: 123456
 
-# add a read-only deploy key to a repository hosted on GitHub Enterprise
-- github_deploy_key:
+- name: Add a read-only deploy key to a repository hosted on GitHub Enterprise
+  github_deploy_key:
     github_url: "https://api.example.com"
     owner: "janedoe"
     repo: "example"

plugins/modules/source_control/github/github_hooks.py

@@ -60,17 +60,18 @@ author: "Phillip Gentry, CX Inc (@pcgentry)"
 '''
 
 EXAMPLES = '''
-# Example creating a new service hook. It ignores duplicates.
-- github_hooks:
+- name: Create a new service hook ignoring duplicates
+  github_hooks:
     action: create
     hookurl: http://11.111.111.111:2222
     user: '{{ gituser }}'
     oauthkey: '{{ oauthkey }}'
     repo: https://api.github.com/repos/pcgentry/Github-Auto-Deploy
 
-# Cleaning all hooks for this repo that had an error on the last update. Since this works for all hooks in a repo it is probably best that this would
-# be called from a handler.
-- github_hooks:
+# Cleaning all hooks for this repo that had an error on the last update.
+# Since this works for all hooks in a repo it is probably best that this would be called from a handler.
+- name: Clean all hooks
+  github_hooks:
     action: cleanall
     user: '{{ gituser }}'
     oauthkey: '{{ oauthkey }}'

plugins/modules/storage/hpe3par/ss_3par_cpg.py

@@ -92,31 +92,31 @@ extends_documentation_fragment:
 
 
 EXAMPLES = r'''
-    - name: Create CPG sample_cpg
-      ss_3par_cpg:
-        storage_system_ip: 10.10.10.1
-        storage_system_username: username
-        storage_system_password: password
-        state: present
-        cpg_name: sample_cpg
-        domain: sample_domain
-        growth_increment: 32000 MiB
-        growth_limit: 64000 MiB
-        growth_warning: 48000 MiB
-        raid_type: R6
-        set_size: 8
-        high_availability: MAG
-        disk_type: FC
-        secure: no
+- name: Create CPG sample_cpg
+  ss_3par_cpg:
+    storage_system_ip: 10.10.10.1
+    storage_system_username: username
+    storage_system_password: password
+    state: present
+    cpg_name: sample_cpg
+    domain: sample_domain
+    growth_increment: 32000 MiB
+    growth_limit: 64000 MiB
+    growth_warning: 48000 MiB
+    raid_type: R6
+    set_size: 8
+    high_availability: MAG
+    disk_type: FC
+    secure: no
 
-    - name: Delete CPG sample_cpg
-      ss_3par_cpg:
-        storage_system_ip: 10.10.10.1
-        storage_system_username: username
-        storage_system_password: password
-        state: absent
-        cpg_name: sample_cpg
-        secure: no
+- name: Delete CPG sample_cpg
+  ss_3par_cpg:
+    storage_system_ip: 10.10.10.1
+    storage_system_username: username
+    storage_system_password: password
+    state: absent
+    cpg_name: sample_cpg
+    secure: no
 '''
 
 RETURN = r'''

plugins/modules/system/openwrt_init.py

@@ -42,23 +42,23 @@ requirements:
 '''
 
 EXAMPLES = '''
-# Example action to start service httpd, if not running
-- openwrt_init:
+- name: Start service httpd, if not running
+  openwrt_init:
     state: started
     name: httpd
 
-# Example action to stop service cron, if running
-- openwrt_init:
+- name: Stop service cron, if running
+  openwrt_init:
     name: cron
     state: stopped
 
-# Example action to reload service httpd, in all cases
-- openwrt_init:
+- name: Reload service httpd, in all cases
+  openwrt_init:
     name: httpd
     state: reloaded
 
-# Example action to enable service httpd
-- openwrt_init:
+- name: Enable service httpd
+  openwrt_init:
     name: httpd
     enabled: yes
 '''

plugins/modules/system/osx_defaults.py

@@ -70,6 +70,8 @@ notes:
 '''
 
 EXAMPLES = r'''
+# TODO: Describe what happens in each example
+
 - osx_defaults:
     domain: com.apple.Safari
     key: IncludeInternalDebugMenu

plugins/modules/web_infrastructure/apache2_mod_proxy.py

@@ -54,38 +54,46 @@ options:
 '''
 
 EXAMPLES = '''
-# Get all current balancer pool members' attributes:
-- apache2_mod_proxy:
+- name: Get all current balancer pool members attributes
+  apache2_mod_proxy:
     balancer_vhost: 10.0.0.2
 
-# Get a specific member's attributes:
-- apache2_mod_proxy:
+- name: Get a specific member attributes
+  apache2_mod_proxy:
     balancer_vhost: myws.mydomain.org
     balancer_suffix: /lb/
     member_host: node1.myws.mydomain.org
 
 # Enable all balancer pool members:
-- apache2_mod_proxy:
+- name: Get attributes
+  apache2_mod_proxy:
     balancer_vhost: '{{ myloadbalancer_host }}'
   register: result
-- apache2_mod_proxy:
+
+- name: Enable all balancer pool members
+  apache2_mod_proxy:
     balancer_vhost: '{{ myloadbalancer_host }}'
     member_host: '{{ item.host }}'
     state: present
   with_items: '{{ result.members }}'
 
 # Gracefully disable a member from a loadbalancer node:
-- apache2_mod_proxy:
+- name: Step 1
+  apache2_mod_proxy:
     balancer_vhost: '{{ vhost_host }}'
     member_host: '{{ member.host }}'
     state: drained
   delegate_to: myloadbalancernode
-- wait_for:
+
+- name: Step 2
+  wait_for:
     host: '{{ member.host }}'
     port: '{{ member.port }}'
     state: drained
   delegate_to: myloadbalancernode
-- apache2_mod_proxy:
+
+- name: Step 3
+  apache2_mod_proxy:
     balancer_vhost: '{{ vhost_host }}'
     member_host: '{{ member.host }}'
     state: absent

plugins/modules/web_infrastructure/apache2_module.py

@@ -49,26 +49,30 @@ requirements: ["a2enmod","a2dismod"]
 '''
 
 EXAMPLES = '''
-# enables the Apache2 module "wsgi"
-- apache2_module:
+- name: Enable the Apache2 module wsgi
+  apache2_module:
     state: present
     name: wsgi
-# disables the Apache2 module "wsgi"
-- apache2_module:
+
+- name: Disables the Apache2 module wsgi
+  apache2_module:
     state: absent
     name: wsgi
-# disable default modules for Debian
-- apache2_module:
+
+- name: Disable default modules for Debian
+  apache2_module:
     state: absent
     name: autoindex
     force: True
-# disable mpm_worker and ignore warnings about missing mpm module
-- apache2_module:
+
+- name: Disable mpm_worker and ignore warnings about missing mpm module
+  apache2_module:
     state: absent
     name: mpm_worker
     ignore_configcheck: True
-# enable dump_io module, which is identified as dumpio_module inside apache2
-- apache2_module:
+
+- name: Enable dump_io module, which is identified as dumpio_module inside apache2
+  apache2_module:
     state: present
     name: dump_io
     identifier: dumpio_module

plugins/modules/web_infrastructure/django_manage.py

@@ -97,33 +97,33 @@ author: "Scott Anderson (@tastychutney)"
 '''
 
 EXAMPLES = """
-# Run cleanup on the application installed in 'django_dir'.
-- django_manage:
+- name: Run cleanup on the application installed in django_dir
+  django_manage:
     command: cleanup
     app_path: "{{ django_dir }}"
 
-# Load the initial_data fixture into the application
-- django_manage:
+- name: Load the initial_data fixture into the application
+  django_manage:
     command: loaddata
     app_path: "{{ django_dir }}"
     fixtures: "{{ initial_data }}"
 
-# Run syncdb on the application
-- django_manage:
+- name: Run syncdb on the application
+  django_manage:
     command: syncdb
     app_path: "{{ django_dir }}"
     settings: "{{ settings_app_name }}"
     pythonpath: "{{ settings_dir }}"
     virtualenv: "{{ virtualenv_dir }}"
 
-# Run the SmokeTest test case from the main app. Useful for testing deploys.
-- django_manage:
+- name: Run the SmokeTest test case from the main app. Useful for testing deploys
+  django_manage:
     command: test
     app_path: "{{ django_dir }}"
     apps: main.SmokeTest
 
-# Create an initial superuser.
-- django_manage:
+- name: Create an initial superuser
+  django_manage:
     command: "createsuperuser --noinput --username=admin --email=admin@example.com"
     app_path: "{{ django_dir }}"
 """

plugins/modules/web_infrastructure/htpasswd.py

@@ -63,8 +63,8 @@ extends_documentation_fragment: files
 '''
 
 EXAMPLES = """
-# Add a user to a password file and ensure permissions are set
-- htpasswd:
+- name: Add a user to a password file and ensure permissions are set
+  htpasswd:
     path: /etc/nginx/passwdfile
     name: janedoe
     password: '9s36?;fyNp'
@@ -72,14 +72,14 @@ EXAMPLES = """
     group: www-data
     mode: 0640
 
-# Remove a user from a password file
-- htpasswd:
+- name: Remove a user from a password file
+  htpasswd:
     path: /etc/apache2/passwdfile
     name: foobar
     state: absent
 
-# Add a user to a password file suitable for use by libpam-pwdfile
-- htpasswd:
+- name: Add a user to a password file suitable for use by libpam-pwdfile
+  htpasswd:
     path: /etc/mail/passwords
     name: alex
     password: oedu2eGh

plugins/modules/web_infrastructure/supervisorctl.py

@@ -55,32 +55,32 @@ author:
 '''
 
 EXAMPLES = '''
-# Manage the state of program to be in 'started' state.
-- supervisorctl:
+- name: Manage the state of program to be in started state
+  supervisorctl:
     name: my_app
     state: started
 
-# Manage the state of program group to be in 'started' state.
-- supervisorctl:
+- name: Manage the state of program group to be in started state
+  supervisorctl:
     name: 'my_apps:'
     state: started
 
-# Restart my_app, reading supervisorctl configuration from a specified file.
-- supervisorctl:
+- name: Restart my_app, reading supervisorctl configuration from a specified file
+  supervisorctl:
     name: my_app
     state: restarted
     config: /var/opt/my_project/supervisord.conf
 
-# Restart my_app, connecting to supervisord with credentials and server URL.
-- supervisorctl:
+- name: Restart my_app, connecting to supervisord with credentials and server URL
+  supervisorctl:
     name: my_app
     state: restarted
     username: test
     password: testpass
     server_url: http://localhost:9001
 
-# Send a signal to my_app via supervisorctl
-- supervisorctl:
+- name: Send a signal to my_app via supervisorctl
+  supervisorctl:
     name: my_app
     state: signalled
     signal: USR1

plugins/modules/web_infrastructure/taiga_issue.py

@@ -72,8 +72,8 @@ notes:
 '''
 
 EXAMPLES = '''
-# Create an issue in the my hosted Taiga environment and attach an error log
-- taiga_issue:
+- name: Create an issue in the my hosted Taiga environment and attach an error log
+  taiga_issue:
     taiga_host: https://mytaigahost.example.com
     project: myproject
     subject: An error has been found
@@ -89,8 +89,8 @@ EXAMPLES = '''
       - Needs manual check
     state: present
 
-# Deletes the previously created issue
-- taiga_issue:
+- name: Deletes the previously created issue
+  taiga_issue:
     taiga_host: https://mytaigahost.example.com
     project: myproject
     subject: An error has been found