optimized module docs

lib/ansible/utils/module_docs.py

@@ -52,57 +52,63 @@ def get_docstring(filename, verbose=False):
         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):
+                for t in child.targets:
-                    doc = yaml.safe_load(child.value.s)
+                    try:
-                    fragments = doc.get('extends_documentation_fragment', [])
+                        theid = t.id
-
+                    except AttributeError as e:
-                    if isinstance(fragments, basestring):
+                        continue #TODO: should log these to figure out why this happens
-                        fragments = [ fragments ]
+
-
+                    if 'DOCUMENTATION' in theid:
-                    # Allow the module to specify a var other than DOCUMENTATION
+                        doc = yaml.safe_load(child.value.s)
-                    # to pull the fragment from, using dot notation as a separator
+                        fragments = doc.get('extends_documentation_fragment', [])
-                    for fragment_slug in fragments:
+
-                        fragment_slug = fragment_slug.lower()
+                        if isinstance(fragments, basestring):
-                        if '.' in fragment_slug:
+                            fragments = [ fragments ]
-                            fragment_name, fragment_var = fragment_slug.split('.', 1)
+
-                            fragment_var = fragment_var.upper()
+                        # Allow the module to specify a var other than DOCUMENTATION
-                        else:
+                        # to pull the fragment from, using dot notation as a separator
-                            fragment_name, fragment_var = fragment_slug, 'DOCUMENTATION'
+                        for fragment_slug in fragments:
-
+                            fragment_slug = fragment_slug.lower()
-                        fragment_class = fragment_loader.get(fragment_name)
+                            if '.' in fragment_slug:
-                        assert fragment_class is not None
+                                fragment_name, fragment_var = fragment_slug.split('.', 1)
-
+                                fragment_var = fragment_var.upper()
-                        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):
+                                fragment_name, fragment_var = fragment_slug, 'DOCUMENTATION'
-                                    doc[key].update(value)
+
-                                elif isinstance(doc[key], MutableSet):
+                            fragment_class = fragment_loader.get(fragment_name)
-                                    doc[key].add(value)
+                            assert fragment_class is not None
-                                elif isinstance(doc[key], MutableSequence):
+
-                                    doc[key] = sorted(frozenset(doc[key] + value))
+                            fragment_yaml = getattr(fragment_class, fragment_var, '{}')
-                                else:
+                            fragment = yaml.safe_load(fragment_yaml)
-                                    raise Exception("Attempt to extend a documentation fragement of unknown type")
 
-                if 'EXAMPLES' in (t.id for t in child.targets):
+                            if fragment.has_key('notes'):
-                    plainexamples = child.value.s[1:]  # Skip first empty line
+                                notes = fragment.pop('notes')
+                                if notes:
+                                    if not doc.has_key('notes'):
+                                        doc['notes'] = []
+                                    doc['notes'].extend(notes)
 
-                if 'RETURN' in (t.id for t in child.targets):
+                            if 'options' not in fragment.keys():
-                    returndocs = child.value.s[1:]
+                                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: