draft to generate man pages

This commit is contained in:
Brian Coca 2017-03-22 16:38:49 -04:00 committed by Brian Coca
commit b4c47ebf68
8 changed files with 170 additions and 14 deletions

View file

@ -90,7 +90,6 @@ class InvalidOptsParser(SortedOptParser):
except optparse.BadOptionError:
pass
class CLI(with_metaclass(ABCMeta, object)):
''' code behind bin/ansible* programs '''
@ -284,15 +283,11 @@ class CLI(with_metaclass(ABCMeta, object)):
@staticmethod
def base_parser(usage="", output_opts=False, runas_opts=False, meta_opts=False, runtask_opts=False, vault_opts=False, module_opts=False,
async_opts=False, connect_opts=False, subset_opts=False, check_opts=False, inventory_opts=False, epilog=None, fork_opts=False,
runas_prompt_opts=False):
async_opts=False, connect_opts=False, subset_opts=False, check_opts=False, inventory_opts=False, epilog=None, fork_opts=False, runas_prompt_opts=False, desc=None):
''' create an options parser for most ansible scripts '''
# TODO: implement epilog parsing
# OptionParser.format_epilog = lambda self, formatter: self.epilog
# base opts
parser = SortedOptParser(usage, version=CLI.version("%prog"))
parser = SortedOptParser(usage, version=CLI.version("%prog"), description=desc, epilog=epilog)
parser.add_option('-v','--verbose', dest='verbosity', default=C.DEFAULT_VERBOSITY, action="count",
help="verbose mode (-vvv for more, -vvvv to enable connection debugging)")
@ -669,3 +664,52 @@ class CLI(with_metaclass(ABCMeta, object)):
if os.pathsep in data:
data = data.split(os.pathsep)[0]
return data
def _opt_doc_list(self, action=None):
''' generate options docs '''
if action:
self.args.append(action)
self.set_action()
results = []
for opt in self.parser.option_list:
res = {
'desc': opt.help,
'options': opt._short_opts + opt._long_opts
}
if opt.action == 'store':
res['arg'] = opt.dest.upper()
results.append(res)
return results
def opts_docs(self, args=None):
''' generate doc structure from options '''
# cli name
name = os.path.basename(sys.argv[0])
if '-' in name:
name = name.split('-')[1]
else:
name = 'adhoc'
# cli info
docs = {
'cli': name,
'usage': self.parser.usage,
'short_desc': self.parser.description
}
if self.VALID_ACTIONS:
myopts = []
for action in self.VALID_ACTIONS:
newopts = self._opt_doc_list(action)
for nopt in newopts:
if nopt not in myopts:
myopts.append(nopt)
docs['options'] = myopts
else:
docs['options'] = self._opt_doc_list()
return docs

View file

@ -46,7 +46,7 @@ except ImportError:
########################################################
class AdHocCLI(CLI):
''' code behind ansible ad-hoc cli'''
''' Ad-hoc Ansible allows you to define and run a single task 'playbook' against a set of hosts '''
def parse(self):
''' create an options parser for bin/ansible '''
@ -63,6 +63,8 @@ class AdHocCLI(CLI):
vault_opts=True,
fork_opts=True,
module_opts=True,
desc="Define and run a single task 'playbook' against a set of hosts",
epilog="Some modules do not make sense in Ad-Hoc (include, meta, etc)",
)
# options unique to ansible ad-hoc
@ -92,7 +94,7 @@ class AdHocCLI(CLI):
)
def run(self):
''' use Runner lib to do SSH things '''
''' create and execute the single task playbook '''
super(AdHocCLI, self).run()

View file

@ -79,7 +79,7 @@ class ConsoleCLI(CLI, cmd.Cmd):
def parse(self):
self.parser = CLI.base_parser(
usage='%prog <host-pattern> [options]',
usage='%prog [<host-pattern>] [options]',
runas_opts=True,
inventory_opts=True,
connect_opts=True,
@ -87,6 +87,8 @@ class ConsoleCLI(CLI, cmd.Cmd):
vault_opts=True,
fork_opts=True,
module_opts=True,
desc="REPL console for executing Ansible tasks.",
epilog="This is not a live session/connection, each task executes in the background and returns it's results."
)
# options unique to shell

View file

@ -50,9 +50,10 @@ class DocCLI(CLI):
def parse(self):
self.parser = CLI.base_parser(
usage='usage: %prog [options] [plugin ...]',
epilog='Show Ansible plugin documentation',
usage='usage: %prog [options] [plugin]',
module_opts=True,
desc="plugin documentation tool",
epilog="See man pages for Ansbile CLI options or website for tutorials https://docs.ansible.com"
)
self.parser.add_option("-l", "--list", action="store_true", default=False, dest='list_dir',

View file

@ -50,7 +50,7 @@ class PlaybookCLI(CLI):
# create parser for CLI options
parser = CLI.base_parser(
usage = "%prog playbook.yml",
usage = "%prog [options] playbook.yml [playbook2 ...]",
connect_opts=True,
meta_opts=True,
runas_opts=True,
@ -61,6 +61,7 @@ class PlaybookCLI(CLI):
vault_opts=True,
fork_opts=True,
module_opts=True,
desc="Runs Ansible playbooks, executing the defined tasks on the targeted hosts.",
)
# ansible playbook specific opts

View file

@ -66,6 +66,7 @@ class PullCLI(CLI):
inventory_opts=True,
module_opts=True,
runas_prompt_opts=True,
desc="pulls playbooks from a VCS repo and executes them for the local host",
)
# options unique to pull

View file

@ -55,7 +55,8 @@ class VaultCLI(CLI):
self.parser = CLI.base_parser(
vault_opts=True,
usage = "usage: %%prog [%s] [--help] [options] vaultfile.yml" % "|".join(self.VALID_ACTIONS),
usage = "usage: %%prog [%s] [options] [vaultfile.yml]" % "|".join(self.VALID_ACTIONS),
desc = "encryption/decryption utility for Ansbile data files",
epilog = "\nSee '%s <command> --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0])
)