Add missing module documentation

Change-Id: I2792589728a198fa66e4110492efabcdd017d89a

releasenotes/notes/module-documentation-a35b1ef77c3f6847.yaml

@@ -0,0 +1,5 @@
+---
+features:
+  - |
+    Ansible-style module documentation has been added to our custom modules
+    so they can be described with the ansible-doc command.

validations/library/advanced_format.py

@@ -18,6 +18,28 @@ from os import path
 
 from ansible.module_utils.basic import *  # noqa
 
+DOCUMENTATION = '''
+---
+module: advanced_format
+short_description: Check for advanced disk format
+description:
+    - Check whether a drive uses advanced format
+options:
+    drive:
+        required: true
+        description:
+            - drive name
+        type: str
+author: "Martin Andre (@mandre)"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+    - name: Detect whether the drive uses Advanced Format
+      advanced_format: drive=vda
+'''
+
 
 def read_int(module, file_path):
     '''Read a file and convert its value to int.

validations/library/haproxy_conf.py

@@ -18,6 +18,28 @@ import re
 
 from ansible.module_utils.basic import *  # NOQA
 
+DOCUMENTATION = '''
+---
+module: haproxy_conf
+short_description: Gather the HAProxy config
+description:
+    - Gather the HAProxy config
+options:
+    path:
+        required: true
+        description:
+            - file path to the config file
+        type: str
+author: "Tomas Sedovic"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+    - name: Gather the HAProxy config
+      haproxy_conf: path=/etc/haproxy/haproxy.cfg
+'''
+
 
 # ConfigParser chokes on both mariadb and haproxy files. Luckily They have
 # a syntax approaching ini config file so they are relatively easy to parse.

validations/library/hiera.py

@@ -18,6 +18,28 @@ import subprocess
 
 from ansible.module_utils.basic import *  # noqa
 
+DOCUMENTATION = '''
+---
+module: hiera
+short_description: Get data from hiera
+description:
+    - Get data from hiera
+options:
+    name:
+        required: true
+        description:
+            - Name to lookup
+        type: str
+author: "Martin Andre (@mandre)"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+    - name: Lookup foo
+      hiera: name=foo
+'''
+
 
 def main():
     module = AnsibleModule(argument_spec=dict(

validations/library/ini.py

@@ -30,6 +30,43 @@ from os import path
 
 from ansible.module_utils.basic import *  # NOQA
 
+DOCUMENTATION = '''
+---
+module: ini
+short_description: Get data from an ini file
+description:
+    - Get data from an ini file
+options:
+    path:
+        required: true
+        description:
+            - File path
+        type: str
+    section:
+        required: true
+        description:
+            - Section to look up
+        type: str
+    key:
+        required: true
+        description:
+            - Section key to look up
+        type: str
+    ignore_missing_file:
+        required: false
+        description:
+            - Flag if a missing file should be ignored
+        type: bool
+author: "Tomas Sedovic"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+    - name: Lookup bar value
+      ini: path=config.ini section=foo key=bar ignore_missing_file=True
+'''
+
 
 def main():
     module = AnsibleModule(argument_spec=dict(

validations/library/ip_range.py

@@ -18,6 +18,41 @@ import netaddr
 
 from ansible.module_utils.basic import *  # NOQA
 
+DOCUMENTATION = '''
+---
+module: ip_range
+short_description: Check the size of an IP range
+description:
+    - Check if the size of an IP range against a minimum value.
+options:
+    start:
+        required: true
+        description:
+            - Start IP
+        type: str
+    end:
+        required: true
+        description:
+            - End IP
+        type: str
+    min_size:
+        required: true
+        description:
+            - Minum size of the range
+        type: int
+author: "Tomas Sedovic"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+    - name: Check the IP range
+      ip_range:
+        start: 192.0.2.5
+        end: 192.0.2.24
+        min_size: 15
+'''
+
 
 def check_arguments(start, end, min_size):
     '''Validate format of arguments'''

validations/library/network_environment.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
 # Copyright 2016 Red Hat, Inc.
 # All Rights Reserved.
 #
@@ -25,6 +26,35 @@ import six
 from ansible.module_utils.basic import AnsibleModule
 from os_net_config import validator
 
+DOCUMENTATION = '''
+---
+module: network_environment
+short_description: Validate networking templates
+description:
+    - Performs networking-related checks on a set of TripleO templates
+options:
+    path:
+        required: true
+        description:
+            - The path of the base network environment file
+        type: str
+    template_files:
+        required: true
+        description:
+            - A list of template files and contents
+        type: list
+author: "Tomas Sedovic, Martin André, Florian Fuchs"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+    - name: Check the Network environment
+      network_environment:
+        path: environments/network-environment.yaml
+        template_files: "{{ lookup('tht') }}"
+'''
+
 
 def open_network_environment_files(netenv_path, template_files):
     errors = []

validations/library/neutron_sanity_check.py

@@ -19,6 +19,36 @@ import subprocess
 from ansible.module_utils.basic import AnsibleModule
 from os import path
 
+DOCUMENTATION = '''
+---
+module: neutron_sanity_check
+short_description: Run neutron-sanity-check on a number of config files
+description:
+    - Run neutron-sanity-check on a number of config files
+options:
+    configs:
+        required: true
+        description:
+           - The config file paths
+        type: list
+author: "Tomas Sedovic"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  vars:
+    configs:
+      - /etc/neutron/neutron.conf
+      - /usr/share/neutron/neutron-dist.conf
+      - /etc/neutron/metadata_agent.ini
+      - /etc/neutron/metering_agent.ini
+      - /etc/neutron/dhcp_agent.ini
+  tasks:
+  - name: Run neutron-sanity-check
+    become: true
+    neutron_sanity_check: configs={{ configs }}
+'''
+
 
 def main():
     module = AnsibleModule(argument_spec=dict(

validations/library/overcloudrc.py

@@ -19,6 +19,28 @@ from ansible.module_utils.basic import *  # NOQA
 import os.path
 import subprocess
 
+DOCUMENTATION = '''
+---
+module: overcloudrc
+short_description: Source the overcloudrc file
+description:
+    - Source the overcloudrc file
+options:
+    path:
+        required: true
+        description:
+           - The file path
+        type: str
+author: "Tomas Sedovic"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+  - name: Source overcloudrc
+    overcloudrc: path=/home/stack/overcloudrc
+'''
+
 
 def main():
     module = AnsibleModule(argument_spec=dict(

validations/library/pacemaker.py

@@ -16,6 +16,32 @@ from xml.etree import ElementTree
 
 from ansible.module_utils.basic import *  # NOQA
 
+DOCUMENTATION = '''
+---
+module: pacemaker
+short_description: Return status from a pacemaker stauts XML
+description:
+    - Return status from a pacemaker stauts XML
+options:
+    status:
+        required: true
+        description:
+           - pacemaker status XML
+        type: str
+author: "Tomas Sedovic"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+  - name: Get pacemaker status
+    become: true
+    command: pcs status xml
+    register: pcs_status
+  - name: Check pacemaker status
+    pacemaker: status="{{ pcs_status.stdout }}"
+'''
+
 
 def parse_pcs_status(pcs_status_xml):
     root = ElementTree.fromstring(pcs_status_xml)

validations/library/undercloud_conf.py

@@ -23,6 +23,36 @@ from os import path
 
 from ansible.module_utils.basic import *  # noqa
 
+DOCUMENTATION = '''
+---
+module: undercloud_conf
+short_description: Read undercloud config file
+description:
+    - Add contents of the undercloud config file to ansible_facts.
+options:
+    undercloud_conf_path:
+        required: true
+        description:
+           - Path to the undercloud_conf file
+        type: str
+    ignore_missing:
+        required: false
+        description:
+           - Ignore missing file
+        type: bool
+author: "Martin Andre (@mandre)"
+'''
+
+EXAMPLES = '''
+- hosts: undercloud
+  tasks:
+  - name: Gather undercloud.conf values
+    become: true
+    undercloud_conf:
+      undercloud_conf_path=/home/stack/undercloud.conf
+      ignore_missing=true
+'''
+
 
 def check_arguments(undercloud_conf_path, ignore_missing):
     '''Validate format of arguments

validations/library/warn.py

@@ -16,6 +16,28 @@
 
 from ansible.module_utils.basic import *  # noqa
 
+DOCUMENTATION = '''
+---
+module: warn
+short_description: Add warning to playbook output
+description:
+    - Add warning to playbook output
+options:
+    msg:
+        required: true
+        description:
+           - The warning text
+        type: str
+author: "Martin Andre (@mandre)"
+'''
+
+EXAMPLES = '''
+- hosts: webservers
+  tasks:
+  - name: Output warning message
+    warn: msg="Warning!"
+'''
+
 
 def main():
     module = AnsibleModule(argument_spec=dict(