From 7b5f89ec7c06ed9b24fcb5c11334e58fc62f7410 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Mon, 24 Feb 2014 20:48:15 -0600 Subject: [PATCH] Use PluginLoader for module docs fragments --- lib/ansible/utils/module_docs.py | 25 +++++++--- .../utils/module_docs_fragments/__init__.py | 0 .../rackspace.py} | 48 +++++++++++-------- lib/ansible/utils/plugins.py | 7 ++- library/cloud/rax | 4 +- library/cloud/rax_clb | 4 +- library/cloud/rax_clb_nodes | 4 +- library/cloud/rax_dns | 4 +- library/cloud/rax_dns_record | 4 +- library/cloud/rax_facts | 4 +- library/cloud/rax_files | 4 +- library/cloud/rax_files_objects | 4 +- library/cloud/rax_keypair | 4 +- library/cloud/rax_network | 4 +- library/cloud/rax_queue | 4 +- 15 files changed, 85 insertions(+), 39 deletions(-) create mode 100644 lib/ansible/utils/module_docs_fragments/__init__.py rename lib/ansible/utils/{module_docs_fragments.py => module_docs_fragments/rackspace.py} (92%) diff --git a/lib/ansible/utils/module_docs.py b/lib/ansible/utils/module_docs.py index c356c973501..140b3217caf 100644 --- a/lib/ansible/utils/module_docs.py +++ b/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') diff --git a/lib/ansible/utils/module_docs_fragments/__init__.py b/lib/ansible/utils/module_docs_fragments/__init__.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/lib/ansible/utils/module_docs_fragments.py b/lib/ansible/utils/module_docs_fragments/rackspace.py similarity index 92% rename from lib/ansible/utils/module_docs_fragments.py rename to lib/ansible/utils/module_docs_fragments/rackspace.py index 23300ba85e9..a49202c500f 100644 --- a/lib/ansible/utils/module_docs_fragments.py +++ b/lib/ansible/utils/module_docs_fragments/rackspace.py @@ -1,4 +1,4 @@ -# (c) 2012, Matt Martz +# (c) 2014, Matt Martz # # 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 . -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)) diff --git a/lib/ansible/utils/plugins.py b/lib/ansible/utils/plugins.py index b1d0117e613..22d74c185a3 100644 --- a/lib/ansible/utils/plugins.py +++ b/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'), + '', +) diff --git a/library/cloud/rax b/library/cloud/rax index 387640753cd..248790037eb 100644 --- a/library/cloud/rax +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_clb b/library/cloud/rax_clb index b462908d540..dbc7f85b196 100644 --- a/library/cloud/rax_clb +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_clb_nodes b/library/cloud/rax_clb_nodes index 38b4d752676..fb12967ec1d 100644 --- a/library/cloud/rax_clb_nodes +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_dns b/library/cloud/rax_dns index d63a9aeaa09..7ed2c926d6f 100644 --- a/library/cloud/rax_dns +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_dns_record b/library/cloud/rax_dns_record index ca5b24de1e8..51dc26b779f 100644 --- a/library/cloud/rax_dns_record +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_facts b/library/cloud/rax_facts index 655b1bbf199..f71982f4243 100644 --- a/library/cloud/rax_facts +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_files b/library/cloud/rax_files index 66dc1b91be5..bdb11a661f5 100644 --- a/library/cloud/rax_files +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_files_objects b/library/cloud/rax_files_objects index ef229d7a95b..9002291ceff 100644 --- a/library/cloud/rax_files_objects +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_keypair b/library/cloud/rax_keypair index fa195fc0d59..6a42e3c99f9 100644 --- a/library/cloud/rax_keypair +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_network b/library/cloud/rax_network index 566016dde64..ac3aca6991e 100644 --- a/library/cloud/rax_network +++ b/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 . +# 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 = ''' diff --git a/library/cloud/rax_queue b/library/cloud/rax_queue index 0faceb128d4..7388c4ed81d 100644 --- a/library/cloud/rax_queue +++ b/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 . +# 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 = '''