Skip to content

A
ansible
Commit 164092a8 by Brian Coca
Options

optimized module docs

parent 65c649aa
Showing with 54 additions and 48 deletions
lib/ansible/utils/module_docs.py
...@@ -52,57 +52,63 @@ def get_docstring(filename, verbose=False): ...@@ -52,57 +52,63 @@ def get_docstring(filename, verbose=False):
M = ast.parse(''.join(open(filename))) M = ast.parse(''.join(open(filename)))
for child in M.body: for child in M.body:
if isinstance(child, ast.Assign): 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: 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: except:
traceback.print_exc() # temp traceback.print_exc() # temp
if verbose == True: if verbose == True:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment