POC of documentation

ansible-doc.py

#!/usr/bin/env python3
"""
Super simple POC
"""
import sys

import markdown
import yaml

filename = sys.argv[1]

with open(filename, 'r') as m:
    md = markdown.Markdown()
    in_module = False
    current_module = ''
    doc = '# {}\n'.format(filename)
    for line in m.readlines():
        if line.startswith('---'):
            break
        doc+=(line[2:])

    # Reset the read point to load YAML
    m.seek(0)
    # Check for includes and set_facts
    includes = []
    sets = []
    task_cnt = 0

    # Read the yaml
    ydata = yaml.load(m.read())
    # And parse out the kind of information we are interested in
    for task in ydata:
        task_cnt += 1
        if 'include' in list(task.keys()):
            # TODO: find the location of the item included when possible
            includes.append('* "{}"'.format(task['include']))

        if 'set_fact' in list(task.keys()):
            for k, v in task['set_fact'].items():
                sets.append('* {}: {}'.format(k, v))

    doc += '\n**Task Count**: {}\n\n'.format(task_cnt)
    doc += '\n**Set Count**: {}\n\n'.format(len(sets))
    doc += '\n**Include Count**: {}\n\n'.format(len(includes))
    doc += '\n## Sets:\n\n{}\n\n'.format('\n'.join(sets))
    doc += '## Includes:\n\n{}\n'.format('\n'.join(includes))

    # Write out the file
    out_name = '{}.html'.format(filename[:filename.rfind('.')])
    with open(out_name, 'w') as out:
        out.write(md.convert(doc))
    sys.stderr.write('+ Wrote {}\n'.format(out_name))

main.html

<h1>main.yaml</h1>
<p>This is my module</p>
<ul>
<li>feature 1</li>
<li>feature 2</li>
<li>feature 3</li>
</ul>
<p><strong>Task Count</strong>: 3</p>
<p><strong>Set Count</strong>: 2</p>
<p><strong>Include Count</strong>: 2</p>
<h2>Sets:</h2>
<ul>
<li>c: d</li>
<li>a: b</li>
</ul>
<h2>Includes:</h2>
<ul>
<li>"{{ role_path }}/tasks/cleanup_logging.yaml"</li>
<li>"{{ role_path }}/tasks/deploy_logging.yaml"</li>
</ul>

main.yaml

#
# This is my module
# 
# * feature 1
# * feature 2
# * feature 3
---
- name: Cleanup logging deployment
  include: "{{ role_path }}/tasks/cleanup_logging.yaml"
  when: openshift_hosted_logging_cleanup | default(false) | bool

- name: blah
  set_fact:
    a: b
    c: d

- name: Deploy logging
  include: "{{ role_path }}/tasks/deploy_logging.yaml"
  when: not openshift_hosted_logging_cleanup | default(false) | bool

Executed via:

./ansible-doc main.yaml

Output is at main.html