Added documentation for nova inventory system

plugins/inventory/nova.py

@@ -1,17 +1,29 @@
 #!/usr/bin/python
 
-"""
+# (c) 2012, Marco Vito Moscaritolo <marco@agavee.com>
-OpenStack external inventory script
+#
-=================================
+# This file is part of Ansible,
-
+#
-Generates inventory that Ansible can understand by making API request to
+# Ansible is free software: you can redistribute it and/or modify
-OpenStack endpoint using the novaclient library.
+# it under the terms of the GNU General Public License as published by
-
+# the Free Software Foundation, either version 3 of the License, or
-NOTE: This script assumes Ansible is being executed where the environment
+# (at your option) any later version.
-variables needed for novaclient have already been set on nova.ini file
+#
-
+# Ansible is distributed in the hope that it will be useful,
-For more details, see: https://github.com/openstack/python-novaclient
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+DOCUMENTATION = '''
+---
+inventory: nova
+short_description: OpenStack external inventory script
+description:
+  - Generates inventory that Ansible can understand by making API request to OpenStack endpoint using the novaclient library.
+  - |
     When run against a specific host, this script returns the following variables:
         os_os-ext-sts_task_state
         os_addresses
@@ -38,27 +50,83 @@ When run against a specific host, this script returns the following variables:
         os__loaded
 
     where some item can have nested structure.
-
+  - All information are set on B(nova.ini) file
-"""
+version_added: None
-
+options:
-# (c) 2012, Marco Vito Moscaritolo <marco@agavee.com>
+  version:
-#
+    description:
-# This file is part of Ansible,
+      - OpenStack version to use.
-#
+    required: true
-# Ansible is free software: you can redistribute it and/or modify
+    default: null
-# it under the terms of the GNU General Public License as published by
+    choices: [ "1.1", "2" ]
-# the Free Software Foundation, either version 3 of the License, or
+  username:
-# (at your option) any later version.
+    description:
-#
+      - Username used to authenticate in OpenStack.
-# Ansible is distributed in the hope that it will be useful,
+    required: true
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
+    default: null
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  api_key:
-# GNU General Public License for more details.
+    description:
-#
+      - Password used to authenticate in OpenStack, can be the ApiKey on some authentication system.
-# You should have received a copy of the GNU General Public License
+    required: true
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+    default: null
-
+  auth_url:
-######################################################################
+    description:
+      - Authentication URL required to generate token.
+      - To manage RackSpace use I(https://identity.api.rackspacecloud.com/v2.0/)
+    required: true
+    default: null
+  auth_system:
+    description:
+      - Authentication system used to login
+      - To manage RackSpace install B(rackspace-novaclient) and insert I(rackspace)
+    required: true
+    default: null
+  region_name:
+    description:
+      - Region name to use in request
+      - In RackSpace some value can be I(ORD) or I(DWF).
+    required: true
+    default: null
+  project_id:
+    description:
+      - Project ID to use in connection
+      - In RackSpace use OS_TENANT_NAME
+    required: false
+    default: null
+  endpoint_type:
+    description:
+      - The endpoint type for novaclient
+      - In RackSpace use 'publicUrl'
+    required: false
+    default: null
+  service_type:
+    description:
+      - The service type you are managing.
+      - In RackSpace use 'compute'
+    required: false
+    default: null
+  service_name:
+    description:
+      - The service name you are managing.
+      - In RackSpace use 'cloudServersOpenStack'
+    required: false
+    default: null
+  insicure:
+    description:
+      - To no check security
+    required: false
+    default: false
+    choices: [ "true", "false" ]
+author: Marco Vito Moscaritolo
+notes:
+  - This script assumes Ansible is being executed where the environment variables needed for novaclient have already been set on nova.ini file
+  - For more details, see U(https://github.com/openstack/python-novaclient)
+examples:
+    - description: List instances
+      code: nova.py --list
+    - description: Instance property
+      code: nova.py --instance INSTANCE_IP
+'''
 
 
 import sys