Add support for shared module documentation fragments

2024-09-14 20:13:21 +02:00 · 2014-02-24 12:47:42 -06:00 · 2014-02-24 12:47:42 -06:00 · bb6f7a267a
commit bb6f7a267a
parent ee0a0b492b
13 changed files with 253 additions and 375 deletions
--- a/lib/ansible/utils/module_docs.py
+++ b/lib/ansible/utils/module_docs.py
@ -23,6 +23,9 @@ import ast
 import yaml
 import traceback

+from ansible.utils import module_docs_fragments as fragments
+
+
 # modules that are ok that they do not have documentation strings
 BLACKLIST_MODULES = [
   'async_wrapper', 'accelerate', 'async_status'
@ -46,6 +49,23 @@ def get_docstring(filename, verbose=False):
            if isinstance(child, ast.Assign):
                if 'DOCUMENTATION' in (t.id for t in child.targets):
                    doc = yaml.safe_load(child.value.s)
+                    fragment_name = doc.get('extends_documentation_fragment',
+                                            'DOESNOTEXIST').upper()
+                    fragment_yaml = getattr(fragments, fragment_name, None)
+                    if fragment_yaml:
+                        fragment = yaml.safe_load(fragment_yaml)
+                        if fragment.has_key('notes'):
+                            notes = fragment.pop('notes')
+                            if notes:
+                                if not doc.has_key('notes'):
+                                    doc['notes'] = []
+                                doc['notes'].extend(notes)
+                        for key, value in fragment.items():
+                            if not doc.has_key(key):
+                                doc[key] = value
+                            else:
+                                doc[key].update(value)
+
                if 'EXAMPLES' in (t.id for t in child.targets):
                    plainexamples = child.value.s[1:]  # Skip first empty line
    except:
--- a/lib/ansible/utils/module_docs_fragments.py
+++ b/lib/ansible/utils/module_docs_fragments.py
@ -0,0 +1,116 @@
+# (c) 2012, Matt Martz <matt@sivel.net>
+#
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# 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/>.
+
+RACKSPACE_AND_OPENSTACK = """
+options:
+  api_key:
+    description:
+      - Rackspace API key (overrides I(credentials))
+    aliases:
+      - password
+  auth_endpoint:
+    description:
+      - The URI of the authentication service
+    default: https://identity.api.rackspacecloud.com/v2.0/
+    version_added: 1.5
+  credentials:
+    description:
+      - File to find the Rackspace credentials in (ignored if I(api_key) and
+        I(username) are provided)
+    default: null
+    aliases:
+      - creds_file
+  env:
+    description:
+      - Environment as configured in ~/.pyrax.cfg,
+        see U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#pyrax-configuration)
+    version_added: 1.5
+  identity_type:
+    description:
+      - Authentication machanism to use, such as rackspace or keystone
+    default: rackspace
+    version_added: 1.5
+  region:
+    description:
+      - Region to create an instance in
+    default: DFW
+  tenant_id:
+    description:
+      - The tenant ID used for authentication
+    version_added: 1.5
+  tenant_name:
+    description:
+      - The tenant name used for authentication
+    version_added: 1.5
+  username:
+    description:
+      - Rackspace username (overrides I(credentials))
+  verify_ssl:
+    description:
+      - Whether or not to require SSL validation of API endpoints
+    version_added: 1.5
+requirements:
+  - pyrax
+notes:
+  - The following environment variables can be used, C(RAX_USERNAME),
+    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
+  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
+    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
+  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
+  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+"""
+
+RACKSPACE = """
+options:
+  api_key:
+    description:
+      - Rackspace API key (overrides I(credentials))
+    aliases:
+      - password
+  credentials:
+    description:
+      - File to find the Rackspace credentials in (ignored if I(api_key) and
+        I(username) are provided)
+    default: null
+    aliases:
+      - creds_file
+  env:
+    description:
+      - Environment as configured in ~/.pyrax.cfg,
+        see U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#pyrax-configuration)
+    version_added: 1.5
+  region:
+    description:
+      - Region to create an instance in
+    default: DFW
+  username:
+    description:
+      - Rackspace username (overrides I(credentials))
+  verify_ssl:
+    description:
+      - Whether or not to require SSL validation of API endpoints
+    version_added: 1.5
+requirements:
+  - pyrax
+notes:
+  - The following environment variables can be used, C(RAX_USERNAME),
+    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
+  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
+    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
+  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
+  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+"""
--- a/library/cloud/rax
+++ b/library/cloud/rax
@ -23,52 +23,6 @@ description:
       waits for it to be 'running'.
 version_added: "1.2"
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides I(credentials))
-    aliases:
-      - password
-  auth_endpoint:
-    description:
-      - The URI of the authentication service
-    default: https://identity.api.rackspacecloud.com/v2.0/
-    version_added: 1.5
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if I(api_key) and
-        I(username) are provided)
-    default: null
-    aliases:
-      - creds_file
-  env:
-    description:
-      - Environment as configured in ~/.pyrax.cfg,
-        see U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#pyrax-configuration)
-    version_added: 1.5
-  identity_type:
-    description:
-      - Authentication machanism to use, such as rackspace or keystone
-    default: rackspace
-    version_added: 1.5
-  region:
-    description:
-      - Region to create an instance in
-    default: DFW
-  tenant_id:
-    description:
-      - The tenant ID used for authentication
-    version_added: 1.5
-  tenant_name:
-    description:
-      - The tenant name used for authentication
-    version_added: 1.5
-  username:
-    description:
-      - Rackspace username (overrides I(credentials))
-  verify_ssl:
-    description:
-      - Whether or not to require SSL validation of API endpoints
-    version_added: 1.5
  auto_increment:
    description:
      - Whether or not to increment a single number with the name of the
@ -89,7 +43,9 @@ options:
  disk_config:
    description:
      - Disk partitioning strategy
-    choices: ['auto', 'manual']
+    choices:
+      - auto
+      - manual
    version_added: '1.4'
    default: auto
  exact_count:
@ -135,7 +91,8 @@ options:
    description:
      - key pair to use on the instance
    default: null
-    aliases: ['keypair']
+    aliases:
+      - keypair
  meta:
    description:
      - A hash of metadata to associate with the instance
@ -149,31 +106,30 @@ options:
      - The network to attach to the instances. If specified, you must include
        ALL networks including the public and private interfaces. Can be C(id)
        or C(label).
-    default: ['public', 'private']
+    default:
+      - public
+      - private
    version_added: 1.4
  state:
    description:
      - Indicate desired state of the resource
-    choices: ['present', 'absent']
+    choices:
+      - present
+      - absent
    default: present
  wait:
    description:
      - wait for the instance to be in state 'running' before returning
    default: "no"
-    choices: [ "yes", "no" ]
+    choices:
+      - "yes"
+      - "no"
  wait_timeout:
    description:
      - how long before wait gives up, in seconds
    default: 300
-requirements: [ "pyrax" ]
 author: Jesse Keating, Matt Martz
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE_AND_OPENSTACK
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_clb
+++ b/library/cloud/rax_clb
@ -25,17 +25,13 @@ options:
  algorithm:
    description:
      - algorithm for the balancer being created
-    choices: ['RANDOM', 'LEAST_CONNECTIONS', 'ROUND_ROBIN', 'WEIGHTED_LEAST_CONNECTIONS', 'WEIGHTED_ROUND_ROBIN']
+    choices:
+      - RANDOM
+      - LEAST_CONNECTIONS
+      - ROUND_ROBIN
+      - WEIGHTED_LEAST_CONNECTIONS
+      - WEIGHTED_ROUND_ROBIN
    default: LEAST_CONNECTIONS
-  api_key:
-    description:
-      - Rackspace API key (overrides C(credentials))
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if C(api_key) and
-        C(username) are provided)
-    default: null
-    aliases: ['creds_file']
  meta:
    description:
      - A hash of metadata to associate with the instance
@ -51,16 +47,32 @@ options:
  protocol:
    description:
      - Protocol for the balancer being created
-    choices: ['DNS_TCP', 'DNS_UDP' ,'FTP', 'HTTP', 'HTTPS', 'IMAPS', 'IMAPv4', 'LDAP', 'LDAPS', 'MYSQL', 'POP3', 'POP3S', 'SMTP', 'TCP', 'TCP_CLIENT_FIRST', 'UDP', 'UDP_STREAM', 'SFTP']
+    choices:
+      - DNS_TCP
+      - DNS_UDP
+      - FTP
+      - HTTP
+      - HTTPS
+      - IMAPS
+      - IMAPv4
+      - LDAP
+      - LDAPS
+      - MYSQL
+      - POP3
+      - POP3S
+      - SMTP
+      - TCP
+      - TCP_CLIENT_FIRST
+      - UDP
+      - UDP_STREAM
+      - SFTP
    default: HTTP
-  region:
-    description:
-      - Region to create the load balancer in
-    default: DFW
  state:
    description:
      - Indicate desired state of the resource
-    choices: ['present', 'absent']
+    choices:
+      - present
+      - absent
    default: present
  timeout:
    description:
@ -69,11 +81,10 @@ options:
  type:
    description:
      - type of interface for the balancer being created
-    choices: ['PUBLIC', 'SERVICENET']
+    choices:
+      - PUBLIC
+      - SERVICENET
    default: PUBLIC
-  username:
-    description:
-      - Rackspace username (overrides C(credentials))
  vip_id:
    description:
      - Virtual IP ID to use when creating the load balancer for purposes of
@ -83,20 +94,15 @@ options:
    description:
      - wait for the balancer to be in state 'running' before returning
    default: "no"
-    choices: [ "yes", "no" ]
+    choices:
+      - "yes"
+      - "no"
  wait_timeout:
    description:
      - how long before wait gives up, in seconds
    default: 300
-requirements: [ "pyrax" ]
 author: Christopher H. Laco, Matt Martz
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_clb_nodes
+++ b/library/cloud/rax_clb_nodes
@ -26,21 +26,15 @@ options:
    required: false
    description:
      - IP address or domain name of the node
-  api_key:
-    required: false
-    description:
-      - Rackspace API key (overrides C(credentials))
  condition:
    required: false
-    choices: [ "enabled", "disabled", "draining" ]
+    choices:
+      - enabled
+      - disabled
+      - draining
    description:
      - Condition for the node, which determines its role within the load
        balancer
-  credentials:
-    required: false
-    description:
-      - File to find the Rackspace credentials in (ignored if C(api_key) and
-        C(username) are provided)
  load_balancer_id:
    required: true
    type: integer
@ -56,35 +50,27 @@ options:
    type: integer
    description:
      - Port number of the load balanced service on the node
-  region:
-    required: false
-    description:
-     - Region to authenticate in
  state:
    required: false
    default: "present"
-    choices: [ "present", "absent" ]
+    choices:
+      - present
+      - absent
    description:
      - Indicate desired state of the node
  type:
    required: false
-    choices: [ "primary", "secondary" ]
+    choices:
+      - primary
+      - secondary
    description:
      - Type of node
-  username:
-    required: false
-    description:
-     - Rackspace username (overrides C(credentials))
-  virtualenv:
-    required: false
-    description:
-      - Path to a virtualenv that should be activated before doing anything.
-        The virtualenv has to already exist. Useful if installing pyrax
-        globally is not an option.
  wait:
    required: false
    default: "no"
-    choices: [ "yes", "no" ]
+    choices:
+      - "yes"
+      - "no"
    description:
      - Wait for the load balancer to become active before returning
  wait_timeout:
@ -97,11 +83,8 @@ options:
    required: false
    description:
      - Weight of node
-requirements: [ "pyrax" ]
 author: Lukasz Kawczynski
-notes:
-  - "The following environment variables can be used: C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDENTIALS) and C(RAX_REGION)."
+extends_documentation_fragment: RACKSPACE
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_dns
+++ b/library/cloud/rax_dns
@ -22,18 +22,9 @@ description:
     - Manage domains on Rackspace Cloud DNS
 version_added: 1.5
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides C(credentials))
  comment:
    description:
      - Brief description of the domain. Maximum length of 160 characters
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if C(api_key) and
-        C(username) are provided)
-    default: null
-    aliases: ['creds_file']
  email:
    desctiption:
      - Email address of the domain administrator
@ -43,24 +34,16 @@ options:
  state:
    description:
      - Indicate desired state of the resource
-    choices: ['present', 'absent']
+    choices:
+      - present
+      - absent
    default: present
  ttl:
    description:
      - Time to live of domain in seconds
    default: 3600
-  username:
-    description:
-      - Rackspace username (overrides C(credentials))
-requirements: [ "pyrax" ]
 author: Matt Martz
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_dns_record
+++ b/library/cloud/rax_dns_record
@ -22,18 +22,9 @@ description:
     - Manage DNS records on Rackspace Cloud DNS
 version_added: 1.5
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides C(credentials))
  comment:
    description:
      - Brief description of the domain. Maximum length of 160 characters
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if C(api_key) and
-        C(username) are provided)
-    default: null
-    aliases: ['creds_file']
  data:
    description:
      - IP address for A/AAAA record, FQDN for CNAME/MX/NS, or text data for
@ -54,7 +45,9 @@ options:
  state:
    description:
      - Indicate desired state of the resource
-    choices: ['present', 'absent']
+    choices:
+      - present
+      - absent
    default: present
  ttl:
    description:
@ -63,20 +56,17 @@ options:
  type:
    description:
      - DNS record type
-    choices: ['A', 'AAAA', 'CNAME', 'MX', 'NS', 'SRV', 'TXT']
+    choices:
+      - A
+      - AAAA
+      - CNAME
+      - MX
+      - NS
+      - SRV
+      - TXT
    default: A
-  username:
-    description:
-      - Rackspace username (overrides C(credentials))
-requirements: [ "pyrax" ]
 author: Matt Martz
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_facts
+++ b/library/cloud/rax_facts
@ -22,52 +22,6 @@ description:
     - Gather facts for Rackspace Cloud Servers.
 version_added: "1.4"
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides I(credentials))
-    aliases:
-      - password
-  auth_endpoint:
-    description:
-      - The URI of the authentication service
-    default: https://identity.api.rackspacecloud.com/v2.0/
-    version_added: 1.5
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if I(api_key) and
-        I(username) are provided)
-    default: null
-    aliases:
-      - creds_file
-  env:
-    description:
-      - Environment as configured in ~/.pyrax.cfg,
-        see https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#pyrax-configuration
-    version_added: 1.5
-  identity_type:
-    description:
-      - Authentication machanism to use, such as rackspace or keystone
-    default: rackspace
-    version_added: 1.5
-  region:
-    description:
-      - Region to create an instance in
-    default: DFW
-  tenant_id:
-    description:
-      - The tenant ID used for authentication
-    version_added: 1.5
-  tenant_name:
-    description:
-      - The tenant name used for authentication
-    version_added: 1.5
-  username:
-    description:
-      - Rackspace username (overrides I(credentials))
-  verify_ssl:
-    description:
-      - Whether or not to require SSL validation of API endpoints
-    version_added: 1.5
  address:
    description:
      - Server IP address to retrieve facts for, will match any IP assigned to
@ -79,15 +33,8 @@ options:
    description:
      - Server name to retrieve facts for
    default: null
-requirements: [ "pyrax" ]
 author: Matt Martz
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE_AND_OPENSTACK
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_files
+++ b/library/cloud/rax_files
@ -25,25 +25,18 @@ description:
  - Manipulate Rackspace Cloud Files Containers
 version_added: "1.5"
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides I(credentials))
  clear_meta:
    description:
      - Optionally clear existing metadata when applying metadata to existing containers.
        Selecting this option is only appropriate when setting type=meta
-    choices: ["yes", "no"]
+    choices:
+      - "yes"
+      - "no"
    default: "no"
  container:
    description:
      - The container to use for container or metadata operations.
    required: true
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if I(api_key) and
-        I(username) are provided)
-    default: null
-    aliases: ['creds_file']
  meta:
    description:
      - A hash of items to set as metadata values on a container
@ -71,26 +64,18 @@ options:
  type:
    description:
      - Type of object to do work on, i.e. metadata object or a container object
-    choices: ["file", "meta"]
-    default: "file"
-  username:
-    description:
-      - Rackspace username (overrides I(credentials))
+    choices:
+      - file
+      - meta
+    default: file
  web_error:
    description:
       - Sets an object to be presented as the HTTP error page when accessed by the CDN URL
  web_index:
    description:
       - Sets an object to be presented as the HTTP index page when accessed by the CDN URL
-requirements: [ "pyrax" ]
 author: Paul Durivage
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_files_objects
+++ b/library/cloud/rax_files_objects
@ -25,26 +25,19 @@ description:
  - Upload, download, and delete objects in Rackspace Cloud Files
 version_added: "1.5"
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides I(credentials))
-    default: null
  clear_meta:
    description:
      - Optionally clear existing metadata when applying metadata to existing objects.
        Selecting this option is only appropriate when setting type=meta
-    choices: ["yes", "no"]
+    choices:
+      - "yes"
+      - "no"
    default: "no"
  container:
    description:
      - The container to use for file object operations.
    required: true
    default: null
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if I(api_key) and I(username) are provided)
-    default: null
-    aliases: ['creds_file']
  dest:
    description:
      - The destination of a "get" operation; i.e. a local directory, "/home/user/myfolder".
@ -64,12 +57,11 @@ options:
      - The method of operation to be performed.  For example, put to upload files
        to Cloud Files, get to download files from Cloud Files or delete to delete
        remote objects in Cloud Files
-    choices: ["get", "put", "delete"]
-    default: "get"
-  region:
-    description:
-      - Region in which to work.  Maps to a Rackspace Cloud region, i.e. DFW, ORD, IAD, SYD, LON
-    default: DFW
+    choices:
+      - get
+      - put
+      - delete
+    default: get
  src:
    description:
      - Source from which to upload files.  Used to specify a remote object as a source for
@ -81,7 +73,9 @@ options:
      - Used to specify whether to maintain nested directory structure when downloading objects
        from Cloud Files.  Setting to false downloads the contents of a container to a single,
        flat directory
-    choices: ["yes", "no"]
+    choices:
+      - yes
+      - "no"
    default: "yes"
  state:
    description:
@ -92,21 +86,12 @@ options:
    description:
      - Type of object to do work on
      - Metadata object or a file object
-    choices: ["file", "meta"]
-    default: "file"
-  username:
-    description:
-      - Rackspace username (overrides I(credentials))
-    default: null
-requirements: [ "pyrax" ]
+    choices:
+      - file
+      - meta
+    default: file
 author: Paul Durivage
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME), C(RAX_API_KEY),
-    C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file appropriate
-    for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_keypair
+++ b/library/cloud/rax_keypair
@ -22,52 +22,6 @@ description:
     - Create a keypair for use with Rackspace Cloud Servers
 version_added: 1.5
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides I(credentials))
-    aliases:
-      - password
-  auth_endpoint:
-    description:
-      - The URI of the authentication service
-    default: https://identity.api.rackspacecloud.com/v2.0/
-    version_added: 1.5
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if I(api_key) and
-        I(username) are provided)
-    default: null
-    aliases:
-      - creds_file
-  env:
-    description:
-      - Environment as configured in ~/.pyrax.cfg,
-        see https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#pyrax-configuration
-    version_added: 1.5
-  identity_type:
-    description:
-      - Authentication machanism to use, such as rackspace or keystone
-    default: rackspace
-    version_added: 1.5
-  region:
-    description:
-      - Region to create an instance in
-    default: DFW
-  tenant_id:
-    description:
-      - The tenant ID used for authentication
-    version_added: 1.5
-  tenant_name:
-    description:
-      - The tenant name used for authentication
-    version_added: 1.5
-  username:
-    description:
-      - Rackspace username (overrides I(credentials))
-  verify_ssl:
-    description:
-      - Whether or not to require SSL validation of API endpoints
-    version_added: 1.5
  name:
    description:
      - Name of keypair
@ -79,19 +33,15 @@ options:
  state:
    description:
      - Indicate desired state of the resource
-    choices: ['present', 'absent']
+    choices:
+      - present
+      - absent
    default: present
-requirements: [ "pyrax" ]
 author: Matt Martz
 notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
  - Keypairs cannot be manipulated, only created and deleted. To "update" a
    keypair you must first delete and then recreate.
+extends_documentation_fragment: RACKSPACE_AND_OPENSTACK
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_network
+++ b/library/cloud/rax_network
@ -25,20 +25,10 @@ options:
  state:
    description:
     - Indicate desired state of the resource
-    choices: ['present', 'absent']
+    choices:
+      - present
+      - absent
    default: present
-  credentials:
-    description:
-     - File to find the Rackspace credentials in (ignored if C(api_key) and
-       C(username) are provided)
-    default: null
-    aliases: ['creds_file']
-  api_key:
-    description:
-     - Rackspace API key (overrides C(credentials))
-  username:
-    description:
-     - Rackspace username (overrides C(credentials))
  label:
    description:
     - Label (name) to give the network
@ -47,19 +37,8 @@ options:
    description:
     - cidr of the network being created
    default: null
-  region:
-    description:
-     - Region to create the network in
-    default: DFW
-requirements: [ "pyrax" ]
 author: Christopher H. Laco, Jesse Keating
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS) points to a credentials file
-    appropriate for pyrax
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE_AND_OPENSTACK
 '''

 EXAMPLES = '''
--- a/library/cloud/rax_queue
+++ b/library/cloud/rax_queue
@ -22,40 +22,19 @@ description:
     - creates / deletes a Rackspace Public Cloud queue.
 version_added: "1.5"
 options:
-  api_key:
-    description:
-      - Rackspace API key (overrides C(credentials))
-  credentials:
-    description:
-      - File to find the Rackspace credentials in (ignored if C(api_key) and
-        C(username) are provided)
-    default: null
-    aliases: ['creds_file']
  name:
    description:
      - Name to give the queue
    default: null
-  region:
-    description:
-      - Region to create the load balancer in
-    default: DFW
  state:
    description:
      - Indicate desired state of the resource
-    choices: ['present', 'absent']
+    choices:
+      - present
+      - absent
    default: present
-  username:
-    description:
-      - Rackspace username (overrides C(credentials))
-requirements: [ "pyrax" ]
 author: Christopher H. Laco, Matt Martz
-notes:
-  - The following environment variables can be used, C(RAX_USERNAME),
-    C(RAX_API_KEY), C(RAX_CREDS_FILE), C(RAX_CREDENTIALS), C(RAX_REGION).
-  - C(RAX_CREDENTIALS) and C(RAX_CREDS_FILE) points to a credentials file
-    appropriate for pyrax. See U(https://github.com/rackspace/pyrax/blob/master/docs/getting_started.md#authenticating)
-  - C(RAX_USERNAME) and C(RAX_API_KEY) obviate the use of a credentials file
-  - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
+extends_documentation_fragment: RACKSPACE
 '''

 EXAMPLES = '''
@ -68,7 +47,6 @@ EXAMPLES = '''
      local_action:
        module: rax_queue
        credentials: ~/.raxpub
-        client_id: unique-client-name
        name: my-queue
        region: DFW
        state: present