def add_fragments(doc, filename): fragments = doc.get('extends_documentation_fragment', []) 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() 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) assert fragment_class is not None fragment_yaml = getattr(fragment_class, fragment_var, '{}') fragment = AnsibleLoader(fragment_yaml, file_name=filename).get_single_data() if 'notes' in fragment: notes = fragment.pop('notes') if notes: if 'notes' not in doc: doc['notes'] = [] doc['notes'].extend(notes) if 'options' not in fragment: raise Exception( "missing options in fragment (%s), possibly misformatted?: %s" % (fragment_name, filename)) for key, value in fragment.items(): if key not in doc: doc[key] = value else: if isinstance(doc[key], MutableMapping): doc[key].update(value) elif isinstance(doc[key], MutableSet): doc[key].add(value) elif isinstance(doc[key], MutableSequence): doc[key] = sorted(frozenset(doc[key] + value)) else: raise Exception( "Attempt to extend a documentation fragement (%s) of unknown type: %s" % (fragment_name, filename))
def get_docstring(filename, verbose=False): """ Search for assignment of the DOCUMENTATION and EXAMPLES variables 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 plainexamples = None returndocs = None try: # Thank you, Habbie, for this bit of code :-) M = ast.parse(''.join(open(filename))) for child in M.body: if isinstance(child, ast.Assign): for t in child.targets: try: theid = t.id except AttributeError as e: # skip errors can happen when trying to use the normal code display.warning("Failed to assign id for %s on %s, skipping" % (t, filename)) continue if 'DOCUMENTATION' in theid: doc = AnsibleLoader(child.value.s, file_name=filename).get_single_data() fragments = doc.get('extends_documentation_fragment', []) 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() 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) assert fragment_class is not None fragment_yaml = getattr(fragment_class, fragment_var, '{}') fragment = AnsibleLoader(fragment_yaml, file_name=filename).get_single_data() if fragment.has_key('notes'): notes = fragment.pop('notes') if notes: if not doc.has_key('notes'): doc['notes'] = [] doc['notes'].extend(notes) if 'options' not in fragment.keys(): raise Exception("missing options in fragment, possibly misformatted?") for key, value in fragment.items(): if not doc.has_key(key): doc[key] = value else: if isinstance(doc[key], MutableMapping): doc[key].update(value) elif isinstance(doc[key], MutableSet): doc[key].add(value) elif isinstance(doc[key], MutableSequence): doc[key] = sorted(frozenset(doc[key] + value)) else: raise Exception("Attempt to extend a documentation fragement of unknown type") elif 'EXAMPLES' in theid: plainexamples = child.value.s[1:] # Skip first empty line elif 'RETURN' in theid: returndocs = child.value.s[1:] except: display.error("unable to parse %s" % filename) if verbose == True: display.display("unable to parse %s" % filename) raise return doc, plainexamples, returndocs
def get_docstring(filename, verbose=False): """ Search for assignment of the DOCUMENTATION and EXAMPLES variables 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 plainexamples = None returndocs = None metadata = None try: # Thank you, Habbie, for this bit of code :-) M = ast.parse(''.join(open(filename))) for child in M.body: if isinstance(child, ast.Assign): for t in child.targets: try: theid = t.id except AttributeError as e: # skip errors can happen when trying to use the normal code display.warning( "Failed to assign id for %s on %s, skipping" % (t, filename)) continue if 'DOCUMENTATION' == theid: doc = AnsibleLoader( child.value.s, file_name=filename).get_single_data() fragments = doc.get('extends_documentation_fragment', []) 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() 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) assert fragment_class is not None fragment_yaml = getattr(fragment_class, fragment_var, '{}') fragment = AnsibleLoader( fragment_yaml, file_name=filename).get_single_data() if 'notes' in fragment: notes = fragment.pop('notes') if notes: if 'notes' not in doc: doc['notes'] = [] doc['notes'].extend(notes) if 'options' not in fragment: raise Exception( "missing options in fragment (%s), possibly misformatted?: %s" % (fragment_name, filename)) for key, value in fragment.items(): if key not in doc: doc[key] = value else: if isinstance(doc[key], MutableMapping): doc[key].update(value) elif isinstance(doc[key], MutableSet): doc[key].add(value) elif isinstance(doc[key], MutableSequence): doc[key] = sorted( frozenset(doc[key] + value)) else: raise Exception( "Attempt to extend a documentation fragement (%s) of unknown type: %s" % (fragment_name, filename)) elif 'EXAMPLES' == theid: plainexamples = child.value.s[ 1:] # Skip first empty line elif 'RETURN' == theid: returndocs = child.value.s[1:] elif 'ANSIBLE_METADATA' == theid: metadata = child.value if type(metadata).__name__ == 'Dict': metadata = ast.literal_eval(child.value) else: # try yaml loading metadata = AnsibleLoader( child.value.s, file_name=filename).get_single_data() if not isinstance(metadata, dict): display.warning( "Invalid metadata detected in %s, using defaults" % filename) metadata = { 'status': ['preview'], 'supported_by': 'community', 'version': '1.0' } except: display.error("unable to parse %s" % filename) if verbose == True: display.display("unable to parse %s" % filename) raise if not metadata: metadata = dict() # ensure metadata defaults # FUTURE: extract this into its own class for use by runtime metadata metadata['version'] = metadata.get('version', '1.0') metadata['status'] = metadata.get('status', ['preview']) metadata['supported_by'] = metadata.get('supported_by', 'community') return doc, plainexamples, returndocs, metadata
def get_docstring(filename, verbose=False): """ Search for assignment of the DOCUMENTATION and EXAMPLES variables 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 plainexamples = None returndocs = None try: # Thank you, Habbie, for this bit of code :-) M = ast.parse(''.join(open(filename))) for child in M.body: if isinstance(child, ast.Assign): for t in child.targets: try: theid = t.id except AttributeError as e: continue #TODO: should log these to figure out why this happens if 'DOCUMENTATION' in theid: doc = yaml.safe_load(child.value.s) fragments = doc.get('extends_documentation_fragment', []) if isinstance(fragments, basestring): 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() 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) assert fragment_class is not None fragment_yaml = getattr(fragment_class, fragment_var, '{}') fragment = yaml.safe_load(fragment_yaml) if fragment.has_key('notes'): notes = fragment.pop('notes') if notes: if not doc.has_key('notes'): doc['notes'] = [] doc['notes'].extend(notes) if 'options' not in fragment.keys(): raise Exception("missing options in fragment, possibly misformatted?") for key, value in fragment.items(): if not doc.has_key(key): doc[key] = value else: if isinstance(doc[key], MutableMapping): doc[key].update(value) elif isinstance(doc[key], MutableSet): doc[key].add(value) elif isinstance(doc[key], MutableSequence): doc[key] = sorted(frozenset(doc[key] + value)) else: raise Exception("Attempt to extend a documentation fragement of unknown type") elif 'EXAMPLES' in theid: plainexamples = child.value.s[1:] # Skip first empty line elif 'RETURN' in theid: returndocs = child.value.s[1:] except: traceback.print_exc() # temp if verbose == True: traceback.print_exc() print "unable to parse %s" % filename return doc, plainexamples, returndocs
def get_docstring(filename, verbose=False): """ Search for assignment of the DOCUMENTATION and EXAMPLES variables 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 plainexamples = None returndocs = None try: # Thank you, Habbie, for this bit of code :-) M = ast.parse(''.join(open(filename))) for child in M.body: if isinstance(child, ast.Assign): if 'DOCUMENTATION' in (t.id for t in child.targets): doc = yaml.safe_load(child.value.s) 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' if fragment_slug != 'doesnotexist': fragment_class = fragment_loader.get(fragment_name) assert fragment_class is not None fragment_yaml = getattr(fragment_class, fragment_var, '{}') fragment = yaml.safe_load(fragment_yaml) if fragment.has_key('notes'): notes = fragment.pop('notes') if notes: if not doc.has_key('notes'): doc['notes'] = [] doc['notes'].extend(notes) if 'options' not in fragment.keys(): raise Exception( "missing options in fragment, possibly misformatted?" ) for key, value in fragment.items(): if not doc.has_key(key): doc[key] = value else: doc[key].update(value) if 'EXAMPLES' in (t.id for t in child.targets): plainexamples = child.value.s[1:] # Skip first empty line if 'RETURN' in (t.id for t in child.targets): returndocs = child.value.s[1:] except: traceback.print_exc() # temp if verbose == True: traceback.print_exc() print "unable to parse %s" % filename return doc, plainexamples, returndocs
def get_docstring(filename, verbose=False): """ Search for assignment of the DOCUMENTATION and EXAMPLES variables 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 plainexamples = None returndocs = None try: # Thank you, Habbie, for this bit of code :-) M = ast.parse(''.join(open(filename))) for child in M.body: if isinstance(child, ast.Assign): if 'DOCUMENTATION' in (t.id for t in child.targets): doc = yaml.safe_load(child.value.s) 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' if fragment_slug != 'doesnotexist': fragment_class = fragment_loader.get(fragment_name) assert fragment_class is not None fragment_yaml = getattr(fragment_class, fragment_var, '{}') fragment = yaml.safe_load(fragment_yaml) if fragment.has_key('notes'): notes = fragment.pop('notes') if notes: if not doc.has_key('notes'): doc['notes'] = [] doc['notes'].extend(notes) if 'options' not in fragment.keys(): raise Exception("missing options in fragment, possibly misformatted?") for key, value in fragment.items(): if not doc.has_key(key): doc[key] = value else: if isinstance(doc[key], MutableMapping): doc[key].update(value) elif isinstance(doc[key], MutableSet): doc[key].add(value) elif isinstance(doc[key], MutableSequence): doc[key] = sorted(frozenset(doc[key] + value)) else: raise Exception("Attempt to extend a documentation fragement of unknown type") if 'EXAMPLES' in (t.id for t in child.targets): plainexamples = child.value.s[1:] # Skip first empty line if 'RETURN' in (t.id for t in child.targets): returndocs = child.value.s[1:] except: traceback.print_exc() # temp if verbose == True: traceback.print_exc() print "unable to parse %s" % filename return doc, plainexamples, returndocs
def get_docstring(filename, verbose=False): """ Search for assignment of the DOCUMENTATION and EXAMPLES variables 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 plainexamples = None returndocs = None try: # Thank you, Habbie, for this bit of code :-) M = ast.parse(''.join(open(filename))) for child in M.body: if isinstance(child, ast.Assign): for t in child.targets: try: theid = t.id except AttributeError as e: # skip errors can happen when trying to use the normal code display.warning("Failed to assign id for %s on %s, skipping" % (t, filename)) continue if 'DOCUMENTATION' in theid: doc = AnsibleLoader(child.value.s, file_name=filename).get_single_data() fragments = doc.get('extends_documentation_fragment', []) 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() 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) assert fragment_class is not None fragment_yaml = getattr(fragment_class, fragment_var, '{}') fragment = AnsibleLoader(fragment_yaml, file_name=filename).get_single_data() if 'notes' in fragment: notes = fragment.pop('notes') if notes: if 'notes' not in doc: doc['notes'] = [] doc['notes'].extend(notes) if 'options' not in fragment.keys(): raise Exception("missing options in fragment, possibly misformatted?") for key, value in fragment.items(): if key not in doc: doc[key] = value else: if isinstance(doc[key], MutableMapping): doc[key].update(value) elif isinstance(doc[key], MutableSet): doc[key].add(value) elif isinstance(doc[key], MutableSequence): doc[key] = sorted(frozenset(doc[key] + value)) else: raise Exception("Attempt to extend a documentation fragement of unknown type") elif 'EXAMPLES' in theid: plainexamples = child.value.s[1:] # Skip first empty line elif 'RETURN' in theid: returndocs = child.value.s[1:] except: display.error("unable to parse %s" % filename) if verbose == True: display.display("unable to parse %s" % filename) raise return doc, plainexamples, returndocs