ansible/bin/ansible-doc

217 lines
6.8 KiB
Text
Raw Normal View History

#!/usr/bin/env python
# (c) 2012, Jan-Piet Mens <jpmens () gmail.com>
#
# This file is part of Ansible
#
# Ansible 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.
#
# Ansible 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 Ansible. If not, see <http://www.gnu.org/licenses/>.
#
import os
import sys
import yaml
import json
import ast
import textwrap
import re
import optparse
import time
import datetime
from ansible import utils
from ansible import errors
from ansible.utils import module_docs
import ansible.constants as C
2012-12-03 09:01:04 +01:00
from ansible.utils import version
2013-01-26 18:34:30 +01:00
import traceback
MODULEDIR = C.DEFAULT_MODULE_PATH
2012-12-03 09:01:04 +01:00
BLACKLIST_EXTS = ('.swp', '.bak', '~', '.rpm')
_ITALIC = re.compile(r"I\(([^)]+)\)")
_BOLD = re.compile(r"B\(([^)]+)\)")
_MODULE = re.compile(r"M\(([^)]+)\)")
_URL = re.compile(r"U\(([^)]+)\)")
_CONST = re.compile(r"C\(([^)]+)\)")
def tty_ify(text):
t = _ITALIC.sub("`" + r"\1" + "'", text) # I(word) => `word'
t = _BOLD.sub("*" + r"\1" + "*", t) # B(word) => *word*
t = _MODULE.sub("[" + r"\1" + "]", t) # M(word) => [word]
t = _URL.sub(r"\1", t) # U(word) => word
t = _CONST.sub("`" + r"\1" + "'", t) # C(word) => `word'
return t
def print_man(doc):
opt_indent=" "
print "> %s\n" % doc['module'].upper()
desc = "".join(doc['description'])
print "%s\n" % textwrap.fill(tty_ify(desc), initial_indent=" ", subsequent_indent=" ")
2012-12-03 09:01:04 +01:00
if 'option_keys' in doc and len(doc['option_keys']) > 0:
print "Options (= is mandatory):\n"
for o in doc['option_keys']:
opt = doc['options'][o]
if opt.get('required', False):
opt_leadin = "="
else:
opt_leadin = "-"
print "%s %s" % (opt_leadin, o)
desc = "".join(opt['description'])
if 'choices' in opt:
2012-12-03 09:01:04 +01:00
choices = ", ".join(str(i) for i in opt['choices'])
desc = desc + " (Choices: " + choices + ")"
print "%s\n" % textwrap.fill(tty_ify(desc), initial_indent=opt_indent,
subsequent_indent=opt_indent)
if 'notes' in doc and len(doc['notes']) > 0:
notes = "".join(doc['notes'])
print "Notes:%s\n" % textwrap.fill(tty_ify(notes), initial_indent=" ",
subsequent_indent=opt_indent)
2012-12-14 11:12:26 +01:00
if 'examples' in doc and len(doc['examples']) > 0:
print "Example%s:\n" % ('' if len(doc['examples']) < 2 else 's')
for ex in doc['examples']:
print "%s\n" % (ex['code'])
def print_snippet(doc):
desc = tty_ify("".join(doc['short_description']))
print "- name: %s" % (desc)
print " action: %s" % (doc['module'])
for o in doc['options']:
opt = doc['options'][o]
desc = tty_ify("".join(opt['description']))
s = o + "="
2012-12-03 09:01:04 +01:00
print " %-20s # %s" % (s, desc)
def main():
p = optparse.OptionParser(
2012-12-03 09:01:04 +01:00
version=version("%prog"),
usage='usage: %prog [options] [module...]',
description='Show Ansible module documentation',
)
p.add_option("-M", "--module-path",
action="store",
dest="module_path",
default=MODULEDIR,
help="Ansible modules/ directory")
p.add_option("-l", "--list",
action="store_true",
default=False,
dest='list_dir',
help='List available modules')
p.add_option("-s", "--snippet",
action="store_true",
default=False,
dest='show_snippet',
help='Show playbook snippet for specified module(s)')
p.add_option('-v', action='version', help='Show version number and exit')
(options, args) = p.parse_args()
if options.module_path is not None:
2012-12-03 09:01:04 +01:00
for i in options.module_path.split(os.pathsep):
utils.plugins.module_finder.add_directory(i)
if options.list_dir:
# list all modules
paths = utils.plugins.module_finder._get_paths()
module_list = []
for path in paths:
# os.system("ls -C %s" % (path))
if os.path.isdir(path):
for module in os.listdir(path):
2012-12-03 09:01:04 +01:00
if any(module.endswith(x) for x in BLACKLIST_EXTS):
continue
module_list.append(module)
2012-12-03 09:01:04 +01:00
for module in sorted(set(module_list)):
if module in module_docs.BLACKLIST_MODULES:
continue
filename = utils.plugins.module_finder.find_plugin(module)
try:
2012-12-03 09:01:04 +01:00
doc = module_docs.get_docstring(filename)
desc = tty_ify(doc.get('short_description', '?'))
if len(desc) > 55:
desc = desc + '...'
print "%-20s %-60.60s" % (module, desc)
except:
2013-01-26 18:34:30 +01:00
traceback.print_exc()
sys.stderr.write("ERROR: module %s has a documentation error formatting or is missing documentation\n" % module)
pass
sys.exit()
if len(args) == 0:
p.print_help()
for module in args:
filename = utils.plugins.module_finder.find_plugin(module)
if filename is None:
sys.stderr.write("module %s not found in %s\n" % (module,
utils.plugins.module_finder.print_paths()))
continue
2012-12-03 09:01:04 +01:00
if any(filename.endswith(x) for x in BLACKLIST_EXTS):
continue
try:
2012-12-03 09:01:04 +01:00
doc = module_docs.get_docstring(filename)
except:
2013-01-26 18:34:30 +01:00
traceback.print_exc()
sys.stderr.write("ERROR: module %s has a documentation error formatting or is missing documentation\n" % module)
continue
2013-01-26 18:34:30 +01:00
if doc is not None:
all_keys = []
for (k,v) in doc['options'].iteritems():
all_keys.append(k)
all_keys = sorted(all_keys)
doc['option_keys'] = all_keys
doc['filename'] = filename
doc['docuri'] = doc['module'].replace('_', '-')
doc['now_date'] = datetime.date.today().strftime('%Y-%m-%d')
if options.show_snippet:
print_snippet(doc)
else:
print_man(doc)
else:
2013-02-09 20:29:31 +01:00
# this typically means we couldn't even parse the docstring, not just that the YAML is busted,
# probably a quoting issue.
sys.stderr.write("ERROR: module %s missing documentation (or could not parse documentation)\n" % module)
if __name__ == '__main__':
main()