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',
-                                            'DOESNOTEXIST').upper()
-                    fragment_yaml = getattr(fragments, fragment_name, None)
-                    if fragment_yaml:
+                    fragment_slug = doc.get('extends_documentation_fragment',
+                                            'doesnotexist').lower()
+
+                    # 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.py → lib/ansible/utils/module_docs_fragments/rackspace.py

-# (c) 2012, Matt Martz <matt@sivel.net>
+# (c) 2014, Matt Martz <matt@sivel.net>
 #
 # This file is part of Ansible
 #
@@ -15,18 +15,17 @@
 # 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
-  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
@@ -39,23 +38,10 @@ options:
       - 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))
@@ -74,13 +60,20 @@ notes:
   - C(RAX_REGION) defines a Rackspace Public Cloud region (DFW, ORD, LON, ...)
 """
 
-RACKSPACE = """
+    # Documentation fragment including attributes to enable communication
+    # of other OpenStack clouds. Not all rax modules support this.
+    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
@@ -93,10 +86,23 @@ options:
       - 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))

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 = '''