Use PluginLoader for module docs fragments

lib/ansible/utils/module_docs.py

@@ -23,8 +23,7 @@ import ast
 import yaml
 import traceback
 
-from ansible.utils import module_docs_fragments as fragments
+from ansible import utils
-
 
 # modules that are ok that they do not have documentation strings
 BLACKLIST_MODULES = [
@@ -37,6 +36,10 @@ def get_docstring(filename, verbose=False):
     in the given file.
     Parse DOCUMENTATION from YAML and return the YAML doc or None
     together with EXAMPLES, as plain text.
+
+    DOCUMENTATION can be extended using documentation fragments
+    loaded by the PluginLoader from the module_docs_fragments
+    directory.
     """
 
     doc = None
@@ -49,10 +52,20 @@ 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',
+                    fragment_slug = doc.get('extends_documentation_fragment',
-                                            'DOESNOTEXIST').upper()
+                                            'doesnotexist').lower()
-                    fragment_yaml = getattr(fragments, fragment_name, None)
+
-                    if fragment_yaml:
+                    # Allow the module to specify a var other than DOCUMENTATION
+                    # to pull the fragment from, using dot notation as a separator
+                    if '.' in fragment_slug:
+                        fragment_name, fragment_var = fragment_slug.split('.', 1)
+                        fragment_var = fragment_var.upper()
+                    else:
+                        fragment_name, fragment_var = fragment_slug, 'DOCUMENTATION'
+
+                    fragment_class = utils.plugins.fragment_loader.get(fragment_name)
+                    if fragment_class:
+                        fragment_yaml = getattr(fragment_class, fragment_var, '{}')
                         fragment = yaml.safe_load(fragment_yaml)
                         if fragment.has_key('notes'):
                             notes = fragment.pop('notes')

lib/ansible/utils/module_docs_fragments/rackspace.py

@@ -1,4 +1,4 @@
-# (c) 2012, Matt Martz <matt@sivel.net>
+# (c) 2014, Matt Martz <matt@sivel.net>
 #
 # This file is part of Ansible
 #
@@ -15,7 +15,54 @@
 # 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 = """
+
+class ModuleDocFragment(object):
+
+    # Standard Rackspace only documentation fragment
+    DOCUMENTATION = """
+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, ...)
+"""
+
+    # Documentation fragment including attributes to enable communication
+    # of other OpenStack clouds. Not all rax modules support this.
+    OPENSTACK = """
 options:
   api_key:
     description:
@@ -73,44 +120,3 @@ notes:
   - 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, ...)
-"""

lib/ansible/utils/plugins.py

@@ -240,4 +240,9 @@ filter_loader = PluginLoader(
     'filter_plugins'
 )
 
-
+fragment_loader = PluginLoader(
+    'ModuleDocFragment',
+    'ansible.utils.module_docs_fragments',
+    os.path.join(os.path.dirname(__file__), 'module_docs_fragments'),
+    '',
+)

library/cloud/rax

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax
@@ -129,7 +131,7 @@ options:
       - how long before wait gives up, in seconds
     default: 300
 author: Jesse Keating, Matt Martz
-extends_documentation_fragment: RACKSPACE_AND_OPENSTACK
+extends_documentation_fragment: rackspace.openstack
 '''
 
 EXAMPLES = '''

library/cloud/rax_clb

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_clb
@@ -102,7 +104,7 @@ options:
       - how long before wait gives up, in seconds
     default: 300
 author: Christopher H. Laco, Matt Martz
-extends_documentation_fragment: RACKSPACE
+extends_documentation_fragment: rackspace
 '''
 
 EXAMPLES = '''

library/cloud/rax_clb_nodes

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_clb_nodes
@@ -84,7 +86,7 @@ options:
     description:
       - Weight of node
 author: Lukasz Kawczynski
-extends_documentation_fragment: RACKSPACE
+extends_documentation_fragment: rackspace
 '''
 
 EXAMPLES = '''

library/cloud/rax_dns

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_dns
@@ -43,7 +45,7 @@ options:
       - Time to live of domain in seconds
     default: 3600
 author: Matt Martz
-extends_documentation_fragment: RACKSPACE
+extends_documentation_fragment: rackspace
 '''
 
 EXAMPLES = '''

library/cloud/rax_dns_record

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_dns_record
@@ -66,7 +68,7 @@ options:
       - TXT
     default: A
 author: Matt Martz
-extends_documentation_fragment: RACKSPACE
+extends_documentation_fragment: rackspace
 '''
 
 EXAMPLES = '''

library/cloud/rax_facts

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_facts
@@ -34,7 +36,7 @@ options:
       - Server name to retrieve facts for
     default: null
 author: Matt Martz
-extends_documentation_fragment: RACKSPACE_AND_OPENSTACK
+extends_documentation_fragment: rackspace.openstack
 '''
 
 EXAMPLES = '''

library/cloud/rax_files

@@ -17,6 +17,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_files
@@ -75,7 +77,7 @@ options:
     description:
        - Sets an object to be presented as the HTTP index page when accessed by the CDN URL
 author: Paul Durivage
-extends_documentation_fragment: RACKSPACE
+extends_documentation_fragment: rackspace
 '''
 
 EXAMPLES = '''

library/cloud/rax_files_objects

@@ -17,6 +17,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_files_objects
@@ -91,7 +93,7 @@ options:
       - meta
     default: file
 author: Paul Durivage
-extends_documentation_fragment: RACKSPACE
+extends_documentation_fragment: rackspace
 '''
 
 EXAMPLES = '''

library/cloud/rax_keypair

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_keypair
@@ -41,7 +43,7 @@ author: Matt Martz
 notes:
   - 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
+extends_documentation_fragment: rackspace.openstack
 '''
 
 EXAMPLES = '''

library/cloud/rax_network

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_network
@@ -38,7 +40,7 @@ options:
      - cidr of the network being created
     default: null
 author: Christopher H. Laco, Jesse Keating
-extends_documentation_fragment: RACKSPACE_AND_OPENSTACK
+extends_documentation_fragment: rackspace.openstack
 '''
 
 EXAMPLES = '''

library/cloud/rax_queue

@@ -14,6 +14,8 @@
 # You should have received a copy of the GNU General Public License
 # along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
 
+# This is a DOCUMENTATION stub specific to this module, it extends
+# a documentation fragment located in ansible.utils.module_docs_fragments
 DOCUMENTATION = '''
 ---
 module: rax_queue
@@ -34,7 +36,7 @@ options:
       - absent
     default: present
 author: Christopher H. Laco, Matt Martz
-extends_documentation_fragment: RACKSPACE
+extends_documentation_fragment: rackspace
 '''
 
 EXAMPLES = '''