cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Use PluginLoader for module docs fragments

Browse source
This commit is contained in:
Matt Martz 2014-02-24 20:48:15 -06:00 committed by Michael DeHaan
parent bb6f7a267a
commit 7b5f89ec7c
15 changed files with 107 additions and 61 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
lib/ansible/utils/module_docs.py
View file

@ -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')

0
lib/ansible/utils/module_docs_fragments/__init__.py Normal file
View file

92
lib/ansible/utils/module_docs_fragments.py → lib/ansible/utils/module_docs_fragments/rackspace.py
View file

@ -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, ...)
"""

7
lib/ansible/utils/plugins.py
View file

@ -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'),
'',
)

4
library/cloud/rax
View file

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

4
library/cloud/rax_clb
View file

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

4
library/cloud/rax_clb_nodes
View file

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

4
library/cloud/rax_dns
View file

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

4
library/cloud/rax_dns_record
View file

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

4
library/cloud/rax_facts
View file

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

4
library/cloud/rax_files
View file

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

4
library/cloud/rax_files_objects
View file

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

4
library/cloud/rax_keypair
View file

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

4
library/cloud/rax_network
View file

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

4
library/cloud/rax_queue
View file

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