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} | 92 ++++++++++--------- 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, 107 insertions(+), 61 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 c356c97350..140b3217ca 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 0000000000..e69de29bb2 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 23300ba85e..a49202c500 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,7 +15,54 @@ # 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 + 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, ...) -""" diff --git a/lib/ansible/utils/plugins.py b/lib/ansible/utils/plugins.py index b1d0117e61..22d74c185a 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 387640753c..248790037e 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 b462908d54..dbc7f85b19 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 38b4d75267..fb12967ec1 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 d63a9aeaa0..7ed2c926d6 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 ca5b24de1e..51dc26b779 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 655b1bbf19..f71982f424 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 66dc1b91be..bdb11a661f 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 ef229d7a95..9002291cef 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 fa195fc0d5..6a42e3c99f 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 566016dde6..ac3aca6991 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 0faceb128d..7388c4ed81 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 = '''