Build DOCUMENTATION skeleton from argument_spec for an Ansible module

builddocs.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright (C) 2015 Matt Martz <[email protected]>
# Copyright (C) 2015 Rackspace US, Inc.
#
#    This program 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.
#
#    This program 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 this program.  If not, see <http://www.gnu.org/licenses/>.

# This file imports `get_argument_spec` from `validate-modules/module_args`,
# which is not in your PYTHONPATH
# You may need to run this like:
# PYTHONPATH=$PYTHONPATH:/path/to/ansible/test/sanity/validate-modules python builddocs.py /path/to/module.py

from __future__ import print_function

from module_args import get_argument_spec
import yaml
import sys
import os
from ansible import __version__ as ansible_version


module_name, _ = os.path.splitext(os.path.basename(sys.argv[1]))

docs = {
    'module': module_name,
    'version_added': ansible_version,
    'short_description': '',
    'description': [''],
    'options': {},
    'requirements': [],
    'notes': [],
    'author': '',
}

spec = get_argument_spec(sys.argv[1])
for arg, data in spec.items():
    value = {
        'description': ['']
    }
    for item in ('required', 'choices', 'aliases', 'version_added', 'default', 'type', 'description'):
        if item == 'type':
            if item in data and data[item] == 'bool':
                value[item] = 'bool'
        elif item in data:
            value[item] = data[item]

    docs['options'][arg] = value

print(yaml.safe_dump(docs, indent=4, default_flow_style=False))

Example from running against lib/ansible/modules/commands/command.py:

author: ''
description:
- ''
module: command
notes: []
options:
    _raw_params:
        description:
        - ''
    _uses_shell:
        default: false
        description:
        - ''
        type: bool
    chdir:
        description:
        - ''
    creates:
        description:
        - ''
    executable:
        description:
        - ''
    removes:
        description:
        - ''
    warn:
        default: true
        description:
        - ''
        type: bool
requirements: []
short_description: ''
version_added: 2.4.0