Coverage for lib/ansible/utils/plugin_docs.py : 52%

# (c) 2012, Jan-Piet Mens <jpmens () gmail.com> 

# 

# This file is part of Ansible 

# 

# Ansible is free software: you can redistribute it and/or modify 

# it under the terms of the GNU General Public License as published by 

# the Free Software Foundation, either version 3 of the License, or 

# (at your option) any later version. 

# 

# Ansible is distributed in the hope that it will be useful, 

# but WITHOUT ANY WARRANTY; without even the implied warranty of 

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

# GNU General Public License for more details. 

# 

# You should have received a copy of the GNU General Public License 

# along with Ansible. If not, see <http://www.gnu.org/licenses/>. 

# 

# Make coding more python3-ish 

from __future__ import (absolute_import, division, print_function) 

__metaclass__ = type 

from collections import MutableMapping, MutableSet, MutableSequence 

from ansible.errors import AnsibleError, AnsibleAssertionError 

from ansible.module_utils.six import string_types 

from ansible.module_utils._text import to_native 

from ansible.parsing.plugin_docs import read_docstring 

from ansible.parsing.yaml.loader import AnsibleLoader 

try: 

from __main__ import display 

except ImportError: 

from ansible.utils.display import Display 

display = Display() 

# modules that are ok that they do not have documentation strings 

BLACKLIST = { 

'MODULE': frozenset(('async_wrapper',)), 

'CACHE': frozenset(('base',)), 

} 

def merge_fragment(target, source): 

47 ↛ 48line 47 didn't jump to line 48, because the loop on line 47 never started for key, value in source.items(): 

if key in target: 

# assumes both structures have same type 

if isinstance(target[key], MutableMapping): 

value.update(target[key]) 

elif isinstance(target[key], MutableSet): 

value.add(target[key]) 

elif isinstance(target[key], MutableSequence): 

value = sorted(frozenset(value + target[key])) 

else: 

raise Exception("Attempt to extend a documentation fragement, invalid type for %s" % key) 

target[key] = value 

def add_fragments(doc, filename, fragment_loader): 

fragments = doc.pop('extends_documentation_fragment', []) 

65 ↛ 66line 65 didn't jump to line 66, because the condition on line 65 was never true if isinstance(fragments, string_types): 

fragments = [fragments] 

# Allow the module to specify a var other than DOCUMENTATION 

# to pull the fragment from, using dot notation as a separator 

for fragment_slug in fragments: 

fragment_slug = fragment_slug.lower() 

72 ↛ 73line 72 didn't jump to line 73, because the condition on line 72 was never true 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 = fragment_loader.get(fragment_name) 

79 ↛ 80line 79 didn't jump to line 80, because the condition on line 79 was never true if fragment_class is None: 

raise AnsibleAssertionError('fragment_class is None') 

fragment_yaml = getattr(fragment_class, fragment_var, '{}') 

fragment = AnsibleLoader(fragment_yaml, file_name=filename).get_single_data() 

85 ↛ 86line 85 didn't jump to line 86, because the condition on line 85 was never true if 'notes' in fragment: 

notes = fragment.pop('notes') 

if notes: 

if 'notes' not in doc: 

doc['notes'] = [] 

doc['notes'].extend(notes) 

92 ↛ 93line 92 didn't jump to line 93, because the condition on line 92 was never true if 'options' not in fragment: 

raise Exception("missing options in fragment (%s), possibly misformatted?: %s" % (fragment_name, filename)) 

# ensure options themselves are directly merged 

96 ↛ 97line 96 didn't jump to line 97, because the condition on line 96 was never true if 'options' in doc: 

try: 

merge_fragment(doc['options'], fragment.pop('options')) 

except Exception as e: 

raise AnsibleError("%s options (%s) of unknown type: %s" % (to_native(e), fragment_name, filename)) 

else: 

doc['options'] = fragment.pop('options') 

# merge rest of the sections 

try: 

merge_fragment(doc, fragment) 

except Exception as e: 

raise AnsibleError("%s (%s) of unknown type: %s" % (to_native(e), fragment_name, filename)) 

def get_docstring(filename, fragment_loader, verbose=False, ignore_errors=False): 

""" 

DOCUMENTATION can be extended using documentation fragments loaded by the PluginLoader from the module_docs_fragments directory. 

""" 

data = read_docstring(filename, verbose=verbose, ignore_errors=ignore_errors) 

# add fragments to documentation 

119 ↛ 122line 119 didn't jump to line 122, because the condition on line 119 was never false if data.get('doc', False): 

add_fragments(data['doc'], filename, fragment_loader=fragment_loader) 

return data['doc'], data['plainexamples'], data['returndocs'], data['metadata']