From 18a7a1ec31a49294ea76559b5ef0f704be88e118 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Thu, 23 Mar 2017 01:11:40 -0400 Subject: [PATCH] added docs to CLI docstringsadded removed 'now intermediate build files' from repo adjusted gitignore --- .gitignore | 9 +- Makefile | 13 +- docs/bin/generate_man.py | 126 ++++++ docs/man/man1/ansible-console.1.asciidoc.in | 261 ------------- docs/man/man1/ansible-doc.1.asciidoc.in | 91 ----- docs/man/man1/ansible-galaxy.1.asciidoc.in | 384 ------------------- docs/man/man1/ansible-playbook.1.asciidoc.in | 275 ------------- docs/man/man1/ansible-pull.1.asciidoc.in | 238 ------------ docs/man/man1/ansible-vault.1.asciidoc.in | 155 -------- docs/man/man1/ansible.1.asciidoc.in | 260 ------------- docs/templates/man.j2 | 41 +- docs/templates/playbooks_keywords.rst.j2 | 2 + lib/ansible/cli/__init__.py | 53 +-- lib/ansible/cli/adhoc.py | 4 +- lib/ansible/cli/console.py | 5 + lib/ansible/cli/doc.py | 5 +- lib/ansible/cli/galaxy.py | 65 ++-- lib/ansible/cli/playbook.py | 4 +- lib/ansible/cli/pull.py | 36 +- lib/ansible/cli/vault.py | 41 +- test/sanity/pep8/legacy-files.txt | 4 +- 21 files changed, 269 insertions(+), 1803 deletions(-) create mode 100755 docs/bin/generate_man.py delete mode 100644 docs/man/man1/ansible-console.1.asciidoc.in delete mode 100644 docs/man/man1/ansible-doc.1.asciidoc.in delete mode 100644 docs/man/man1/ansible-galaxy.1.asciidoc.in delete mode 100644 docs/man/man1/ansible-playbook.1.asciidoc.in delete mode 100644 docs/man/man1/ansible-pull.1.asciidoc.in delete mode 100644 docs/man/man1/ansible-vault.1.asciidoc.in delete mode 100644 docs/man/man1/ansible.1.asciidoc.in diff --git a/.gitignore b/.gitignore index c85f8018040..c09b5cfaab5 100644 --- a/.gitignore +++ b/.gitignore @@ -19,12 +19,8 @@ rpm-build # Mac OS X stuff... .DS_Store # manpage build stuff... -docs/man/man1/ansible.1 -docs/man/man1/ansible-doc.1 -docs/man/man1/ansible-galaxy.1 -docs/man/man1/ansible-playbook.1 -docs/man/man1/ansible-pull.1 -docs/man/man1/ansible-vault.1 +docs/man/man1/ansible*.1 +docs/man/man1/ansible*.1.asciidoc.in docs/man/man3/* # Sublime stuff *.sublime-project @@ -32,6 +28,7 @@ docs/man/man3/* # docsite stuff... docs/docsite/rst/modules_by_category.rst docs/docsite/rst/playbooks_directives.rst +docs/docsite/rst/playbook_keywords.rst docs/docsite/rst/list_of_*.rst docs/docsite/rst/*_module.rst docs/docsite/*.html diff --git a/Makefile b/Makefile index 0f5010dc327..67b75b2eec6 100644 --- a/Makefile +++ b/Makefile @@ -21,7 +21,8 @@ OS = $(shell uname -s) # Manpages are currently built with asciidoc -- would like to move to markdown # This doesn't evaluate until it's called. The -D argument is the # directory of the target file ($@), kinda like `dirname`. -MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1 docs/man/man1/ansible-doc.1 docs/man/man1/ansible-galaxy.1 + +MANPAGES := ./docs/man/man1/ansible*.1 ifneq ($(shell which a2x 2>/dev/null),) ASCII2MAN = a2x -L -D $(dir $@) -d manpage -f manpage $< ASCII2HTMLMAN = a2x -L -D docs/html/man/ -d manpage -f xhtml @@ -160,7 +161,7 @@ clean: find ./docs/man -type f -name "*.xml" -delete find ./docs/man -type f -name "*.asciidoc" -delete find ./docs/man/man3 -type f -name "*.3" -delete - find ./docs/man/man1 -type f -name "*.1" -delete + rm -f ./docs/man/man1/* @echo "Cleaning up output from test runs" rm -rf test/test_data @echo "Cleaning up RPM building stuff" @@ -191,7 +192,7 @@ sdist: clean docs sdist_upload: clean docs $(PYTHON) setup.py sdist upload 2>&1 |tee upload.log -rpmcommon: $(MANPAGES) sdist +rpmcommon: docs sdist @mkdir -p rpm-build @cp dist/*.gz rpm-build/ @sed -e 's#^Version:.*#Version: $(VERSION)#' -e 's#^Release:.*#Release: $(RPMRELEASE)%{?dist}#' $(RPMSPEC) >rpm-build/$(NAME).spec @@ -301,6 +302,10 @@ deb-src-upload: deb-src webdocs: (cd docs/docsite/; CPUS=$(CPUS) make docs) -docs: $(MANPAGES) +docs: lib/ansible/cli/*.py + mkdir -p ./docs/man/man1/ + PYTHONPATH=./lib ./docs/bin/generate_man.py + make $(MANPAGES) alldocs: docs webdocs + diff --git a/docs/bin/generate_man.py b/docs/bin/generate_man.py new file mode 100755 index 00000000000..337b39c1f6f --- /dev/null +++ b/docs/bin/generate_man.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python + +import os +import io +import sys + +from jinja2 import Environment, FileSystemLoader + +def get_options(optlist): + ''' get actual options ''' + + opts = [] + for opt in optlist: + res = { + 'desc': opt.help, + 'options': opt._short_opts + opt._long_opts + } + if opt.action == 'store': + res['arg'] = opt.dest.upper() + opts.append(res) + + return opts + +def opt_doc_list(cli): + ''' iterate over options lists ''' + + results = [] + for optg in cli.parser.option_groups: + results.extend(get_options(optg.option_list)) + + results.extend(get_options(cli.parser.option_list)) + + return results + +def opts_docs(cli, name): + ''' generate doc structure from options ''' + + # cli name + if '-' in name: + name = name.split('-')[1] + else: + name = 'adhoc' + + # cli info + docs = { + 'cli': name, + 'usage': cli.parser.usage, + 'short_desc': cli.parser.description, + 'long_desc': cli.__doc__, + } + + # force populate parser with per action options + if cli.VALID_ACTIONS: + docs['actions'] = {} + # avoid dupe errors + cli.parser.set_conflict_handler('resolve') + for action in cli.VALID_ACTIONS: + cli.args.append(action) + cli.set_action() + docs['actions'][action] = getattr(cli, 'execute_%s' % action).__doc__ + + docs['options'] = opt_doc_list(cli) + + return docs + +if __name__ == '__main__': + + template_file = 'man.j2' + + # need to be in right dir + os.chdir(os.path.dirname(__file__)) + + allvars = {} + output = {} + cli_list = [] + for binary in os.listdir('../../lib/ansible/cli'): + + if not binary.endswith('.py'): + continue + elif binary == '__init__.py': + continue + + libname = os.path.splitext(binary)[0] + print("Found CLI %s" % libname) + + if libname == 'adhoc': + myclass = 'AdHocCLI' + output[libname] = 'ansible.1.asciidoc.in' + else: + myclass = "%sCLI" % libname.capitalize() + output[libname] = 'ansible-%s.1.asciidoc.in' % libname + + # instanciate each cli and ask its options + mycli = getattr(__import__("ansible.cli.%s" % libname, fromlist=[myclass]), myclass) + cli_object = mycli([]) + try: + cli_object.parse() + except: + # no options passed, we expect errors + pass + + allvars[libname] = opts_docs(cli_object, libname) + + for extras in ('ARGUMENTS'): + if hasattr(cli_object, extras): + allvars[libname][extras.lower()] = getattr(cli_object, extras) + + cli_list = allvars.keys() + for libname in cli_list: + + # template it! + env = Environment(loader=FileSystemLoader('../templates')) + template = env.get_template('man.j2') + + # add rest to vars + tvars = allvars[libname] + tvars['cli_list'] = cli_list + tvars['cli'] = libname + if '-i' in tvars['options']: + print('uses inventory') + + manpage = template.render(tvars) + filename = '../man/man1/%s' % output[libname] + with io.open(filename, 'w') as f: + f.write(manpage) + print("Wrote man docs to %s" % filename) diff --git a/docs/man/man1/ansible-console.1.asciidoc.in b/docs/man/man1/ansible-console.1.asciidoc.in deleted file mode 100644 index beec5845b18..00000000000 --- a/docs/man/man1/ansible-console.1.asciidoc.in +++ /dev/null @@ -1,261 +0,0 @@ -ansible-console(1) -================== -:doctype:manpage -3:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands - -NAME ----- -ansible-console - a REPL for ad-hoc ansible tasks - - -SYNOPSIS --------- -ansible-console [-m module_name] [-a args] [options] [host-pattern] - - -DESCRIPTION ------------ - -*Ansible console* is a REPL that allows for running ad-hoc tasks against -a chosen inventory (based on dominis' ansible-shell). - - -ARGUMENTS ---------- - -*host-pattern*:: - -A name of a group in the inventory, a shell-like glob selecting -hosts in inventory or any combination of the two separated by commas. - -OPTIONS -------- - -*-a* \'_ARGUMENTS_', *--args=*\'_ARGUMENTS_':: - -The 'ARGUMENTS' to pass to the module. - -*-b*, *--become*:: - -Use privilege escalation (specific one depends on become_method), -this does not imply prompting for passwords. - -*K*, *--ask-become-pass*:: - -Ask for privilege escalation password. - -*-k*, *--ask-pass*:: - -Prompt for the connection password, if it is needed for the transport used. -For example, using ssh and not having a key-based authentication with ssh-agent. - -*--ask-su-pass*:: - -Prompt for su password, used with --su (deprecated, use become). - -*--ask-sudo-pass*:: - -Prompt for the password to use with --sudo, if any (deprecated, use become). - -*--ask-vault-pass*:: - -Prompt for vault password. - -*-B* 'NUM', *--background=*'NUM':: - -Run commands in the background, killing the task after 'NUM' seconds. - -*--become-method=*'BECOME_METHOD':: - -Privilege escalation method to use (default=sudo), -valid choices: [ sudo | su | pbrun | pfexec | runas | doas | dzdo ] - -*--become-user=*'BECOME_USER':: - -Run operations as this user (default=root). - -*-C*, *--check*:: - -Do not make any changes on the remote system, but test resources to see what might -have changed. Note this can not scan all possible resource types and is only -a simulation. - -*-c* 'CONNECTION', *--connection=*'CONNECTION':: - -Connection type to use. Most common options are 'paramiko' (SSH), 'ssh', 'winrm' -and 'local'. 'local' is mostly useful for crontab or kickstarts. - -*-e* 'EXTRA_VARS, *--extra-vars=*'EXTRA_VARS':: - -Extra variables to inject into a playbook, in key=value key=value format or -as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify -the file preceded by @ (e.g. @vars.yml). - -*-f* 'NUM', *--forks=*'NUM':: - -Level of parallelism. 'NUM' is specified as an integer, the default is 5. - -*-h*, *--help*:: - -Show help message and exit. - -*-i* 'PATH', *--inventory=*'PATH':: - -The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'. -Alternatively you can use a comma separated list of hosts or single host with traling comma 'host,'. - -*-l* 'SUBSET', *--limit=*'SUBSET':: - -Further limits the selected host/group patterns. -You can prefix it with '~' to indicate that the pattern is a regex. - -*--list-hosts*:: - -Outputs a list of matching hosts; does not execute anything else. - -*-m* 'NAME', *--module-name=*'NAME':: - -Execute the module called 'NAME'. - -*-M* 'DIRECTORY', *--module-path=*'DIRECTORY':: - -The 'DIRECTORY' search path to load modules from. The default is -'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY -environment variable. - -*-o*, *--one-line*:: - -Try to output everything on one line. - -*-P* 'NUM', *--poll=*'NUM':: - -Poll a background job every 'NUM' seconds. Requires *-B*. - -*--private-key=*'PRIVATE_KEY_FILE':: - -Use this file to authenticate the connection. - -*-S*, *--su*:: - -Run operations with su (deprecated, use become). - -*-R* 'SU_USER', *--se-user=*'SUDO_USER':: - -Run operations with su as this user (default=root) (deprecated, use become). - -*-s*, *--sudo*:: - -Run the command as the user given by -u and sudo to root (deprecated, use become). - -*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...'':: - -Add the specified arguments to any sftp/scp/ssh command-line. Useful to -set a ProxyCommand to use a jump host, but any arguments that are -accepted by all three programs may be specified. - -*--sftp-extra-args=*''-f ...'':: - -Add the specified arguments to any sftp command-line. - -*--scp-extra-args=*''-l ...'':: - -Add the specified arguments to any scp command-line. - -*--ssh-extra-args=*''-R ...'':: - -Add the specified arguments to any ssh command-line. - -*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME':: - -Sudo to 'SUDO_USERNAME' default is root. (deprecated, use become). - -*-t* 'DIRECTORY', *--tree=*'DIRECTORY':: - -Save contents in this output 'DIRECTORY', with the results saved in a -file named after each host. - -*-T* 'SECONDS', *--timeout=*'SECONDS':: - -Connection timeout to use when trying to talk to hosts, in 'SECONDS'. - -*-u* 'USERNAME', *--user=*'USERNAME':: - -Use this 'USERNAME' to login to the target host, instead of the current user. - -*--vault-password-file=*'VAULT_PASSWORD_FILE':: - -A file containing the vault password to be used during the decryption of vault encrypted files. -Be sure to keep this file secured if it is used. If the file is executable, -it will be run and its standard output will be used as the password. - -*-v*, *--verbose*:: - -Verbose mode, more output from successful actions will be shown. -Give up to three times for more output. - -*--version*:: - -Show program version number and exit. - -INVENTORY ---------- - -Ansible stores the hosts it can potentially operate on in an inventory. -This can be an ini-like file, a script, directory or a list. -The ini syntax is one host per line. Groups headers are allowed and -are included on their own line, enclosed in square brackets that start the line. - -Ranges of hosts are also supported. For more information and -additional options, see the documentation on http://docs.ansible.com/. - - -ENVIRONMENT ------------ - -The following environment variables may be specified. - -ANSIBLE_INVENTORY -- Override the default ansible inventory file - -ANSIBLE_LIBRARY -- Override the default ansible module library path - -ANSIBLE_CONFIG -- Override the default ansible config file - -Many more are available for most options in ansible.cfg - - -FILES ------ - -/etc/ansible/hosts -- Default inventory file - -/usr/share/ansible/ -- Default module library - -/etc/ansible/ansible.cfg -- Config file, used if present - -~/.ansible.cfg -- User config file, overrides the default config if present - - -AUTHOR ------- - -Ansible was originally written by Michael DeHaan. -See the AUTHORS file for a complete list of contributors. - - -COPYRIGHT ---------- - -Copyright © 2012, Michael DeHaan -Ansible is released under the terms of the GPLv3 License. - - -SEE ALSO --------- - -*ansible-playbook*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1) - -Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: diff --git a/docs/man/man1/ansible-doc.1.asciidoc.in b/docs/man/man1/ansible-doc.1.asciidoc.in deleted file mode 100644 index 089aa928e3f..00000000000 --- a/docs/man/man1/ansible-doc.1.asciidoc.in +++ /dev/null @@ -1,91 +0,0 @@ -ansible-doc(1) -============== -:doctype: manpage -:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands - -NAME ----- -ansible-doc - show documentation on Ansible plugins - - -SYNOPSIS --------- -ansible-doc [-M plugin_path] [-l] [-s] [-t ] [plugin...] - - -DESCRIPTION ------------ - -*ansible-doc* displays information on modules installed in Ansible -libraries. It displays a terse listing of plugins and their short -descriptions, provides a printout of their DOCUMENTATION strings, -and it can create a short "snippet" which can be pasted into a -playbook. - - -OPTIONS -------- - -*-M* 'DIRECTORY', *--plugin-path=*'DIRECTORY':: - -The 'DIRECTORY' search path to load plugins from. -If not specified Ansbile uses it's normal search path and configuration. - -*-s*, *--snippet=*:: - -Produce a snippet which can be copied into a playbook for modification, like a kind of task template. - -*-l*, *--list=*:: - -Produce a terse listing of plugins and a short description of each. - -*-t*, *--type=*:: - -Specify the type of plugin to target, default is 'module'. -Other choices are 'cache', 'callback', 'connection', 'lookup' and 'strategy'. - -ENVIRONMENT ------------ - -ANSIBLE_CONFIG -- Configuration file to use -ANSIBLE_LIBRARY -- Override the default ansible module library path -ANSIBLE_CACHE_PLUGINS -- Override the default ansible cache plugin path -ANSIBLE_CALLBACK_PLUGINS -- Override the default ansible callback plugin path -ANSIBLE_CONNECTION_PLUGINS -- Override the default ansible connection plugin path -ANSIBLE_LOOKUP_PLUGINS -- Override the default ansible lookup plugin path -ANSIBLE_STRATEGY_PLUGINS -- Override the default ansible strategy plugin path - - -FILES ------ - -/etc/ansible/ansible.cfg -- Config file, used if present - -~/.ansible.cfg -- User config file, overrides the default config if present - - - -AUTHOR ------- - -ansible-doc was originally written by Jan-Piet Mens. See the AUTHORS file for a complete list of contributors. - - -COPYRIGHT ---------- - -Copyright © 2012, Jan-Piet Mens - -Ansible is released under the terms of the GPLv3 License. - - -SEE ALSO --------- - -*ansible-playbook*(1), *ansible*(1), *ansible-pull*(1), *ansible-vault*(1), *ansible-galaxy*(1) - -Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: diff --git a/docs/man/man1/ansible-galaxy.1.asciidoc.in b/docs/man/man1/ansible-galaxy.1.asciidoc.in deleted file mode 100644 index cbe75b604f0..00000000000 --- a/docs/man/man1/ansible-galaxy.1.asciidoc.in +++ /dev/null @@ -1,384 +0,0 @@ -ansible-galaxy(1) -=================== -:doctype: manpage -:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands - -NAME ----- -ansible-galaxy - manage roles using galaxy.ansible.com - - -SYNOPSIS --------- -ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ... - - -DESCRIPTION ------------ - -*Ansible Galaxy* is a shared repository for Ansible roles. -The ansible-galaxy command can be used to manage these roles, -or for creating a skeleton framework for roles you'd like to upload to Galaxy. - -COMMON OPTIONS --------------- - -*-h*, *--help*:: - -Show a help message related to the given sub-command. - -INSTALL -------- - -The *install* sub-command is used to install roles. - -USAGE -~~~~~ - -$ ansible-galaxy install [options] [-r FILE | role_name(s)[,version] | tar_file(s)] - -Roles can be installed in several different ways: - -* A username.rolename[,version] - this will install a single role. The Galaxy - API will be contacted to provide the information about the role, and the - corresponding .tar.gz will be downloaded from *github.com*. If the version - is omitted, the most recent version available will be installed. - -* A file name, using *-r* - this will install multiple roles listed one per - line. The format of each line is the same as above: username.rolename[,version] - -* A .tar.gz of a valid role you've downloaded directly from *github.com*. This - is mainly useful when the system running Ansible does not have access to - the Galaxy API, for instance when behind a firewall or proxy. - - -OPTIONS -~~~~~~~ - -*-f*, *--force*:: - -Force overwriting an existing role. - -*-i*, *--ignore-errors*:: - -Ignore errors and continue with the next specified role. - -*-n*, *--no-deps*:: - -Don't download roles listed as dependencies. - -*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH':: - -The path to the directory containing your roles. The default is the *roles_path* -configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) - -*-r* 'ROLE_FILE', *--role-file=*'ROLE_FILE':: - -A file containing a list of roles to be imported, as specified above. This -option cannot be used if a rolename or .tar.gz have been specified. - -REMOVE ------- - -The *remove* sub-command is used to remove one or more roles. - -USAGE -~~~~~ - -$ ansible-galaxy remove role1 role2 ... - -OPTIONS -~~~~~~~ - -*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH':: - -The path to the directory containing your roles. The default is the *roles_path* -configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) - -INIT ----- - -The *init* command is used to create a new role suitable for uploading -to https://galaxy.ansible.com (or for roles in general). Creates a skeleton -directory structure and default files. - -USAGE -~~~~~ - -$ ansible-galaxy init [options] role_name - -OPTIONS -~~~~~~~ - -*-f*, *--force*:: - -Force overwriting an existing role. - -*-p* 'INIT_PATH', *--init-path=*'INIT_PATH':: - -The path in which the skeleton role will be created.The default is the current -working directory. - -*--offline*:: - -Don't query the galaxy API when creating roles - -*--container-enabled*:: - -Initialize the new role with files appropriate for a Container Enabled role. - -*--role-skeleton=*'ROLE_SKELETON':: - -By default a new role is based on a template delivered with Ansible. Use -this option to provide an alternate template. Specify a path to a directory -that contains subdirectories and Jinja templates from which to base the new -role. Alternatively, the role_skeleton option can be configured in -*ansible.cfg*. - -LIST ----- - -The *list* sub-command is used to show what roles are currently installed. -You can specify a role name, and if installed only that role will be shown. - -USAGE -~~~~~ - -$ ansible-galaxy list [role_name] - -OPTIONS -~~~~~~~ - -*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH':: - -The path to the directory containing your roles. The default is the *roles_path* -configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) - - -SEARCH ------- - -The *search* sub-command returns a filtered list of roles found on the remote -server. - - -USAGE -~~~~~ - -$ ansible-galaxy search [options] [searchterm1 searchterm2] - - -OPTIONS -~~~~~~~ -*--galaxy-tags*:: - -Provide a comma separated list of Galaxy Tags on which to filter. - -*--platforms*:: - -Provide a comma separated list of Platforms on which to filter. - -*--author*:: - -Specify the username of a Galaxy contributor on which to filter. - -*-c*, *--ignore-certs*:: - -Ignore TLS certificate errors. - -*-s*, *--server*:: - -Override the default server https://galaxy.ansible.com. - - -INFO ----- - -The *info* sub-command shows detailed information for a specific role. -Details returned about the role included information from the local copy -as well as information from galaxy.ansible.com. - -USAGE -~~~~~ - -$ ansible-galaxy info [options] role_name[, version] - -OPTIONS -~~~~~~~ - -*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH':: - -The path to the directory containing your roles. The default is the *roles_path* -configured in your *ansible.cfg* file (/etc/ansible/roles if not configured) - -*-c*, *--ignore-certs*:: - -Ignore TLS certificate errors. - -*-s*, *--server*:: - -Override the default server https://galaxy.ansible.com. - - -LOGIN ------ - -The *login* sub-command is used to authenticate with galaxy.ansible.com. -Authentication is required to use the import, delete and setup commands. -It will authenticate the user, retrieve a token from Galaxy, and store it -in the user's home directory. - -USAGE -~~~~~ - -$ ansible-galaxy login [options] - -The *login* sub-command prompts for a *GitHub* username and password. It does -NOT send your password to Galaxy. It actually authenticates with GitHub and -creates a personal access token. It then sends the personal access token to -Galaxy, which in turn verifies that you are you and returns a Galaxy access -token. After authentication completes the *GitHub* personal access token is -destroyed. - -If you do not wish to use your GitHub password, or if you have two-factor -authentication enabled with GitHub, use the *--github-token* option to pass a -personal access token that you create. Log into GitHub, go to Settings and -click on Personal Access Token to create a token. - -OPTIONS -~~~~~~~ - -*-c*, *--ignore-certs*:: - -Ignore TLS certificate errors. - -*-s*, *--server*:: - -Override the default server https://galaxy.ansible.com. - -*--github-token*:: - -Authenticate using a *GitHub* personal access token rather than a password. - - -IMPORT ------- - -Import a role from *GitHub* to galaxy.ansible.com. Requires the user first -authenticate with galaxy.ansible.com using the *login* subcommand. - -USAGE -~~~~~ - -$ ansible-galaxy import [options] github_user github_repo - -OPTIONS -~~~~~~~ -*-c*, *--ignore-certs*:: - -Ignore TLS certificate errors. - -*-s*, *--server*:: - -Override the default server https://galaxy.ansible.com. - -*--branch*:: - -Provide a specific branch to import. When a branch is not specified the -branch found in meta/main.yml is used. If no branch is specified in -meta/main.yml, the repo's default branch (usually master) is used. - -*--role-name*:: - -Set the name of the role. Otherwise, the name is derived from the -name of the GitHub repository. - -DELETE ------- - -The *delete* sub-command will delete a role from galaxy.ansible.com. Requires -the user first authenticate with galaxy.ansible.com using the *login* subcommand. - -USAGE -~~~~~ - -$ ansible-galaxy delete [options] github_user github_repo - -OPTIONS -~~~~~~~ - -*-c*, *--ignore-certs*:: - -Ignore TLS certificate errors. - -*-s*, *--server*:: - -Override the default server https://galaxy.ansible.com. - - -SETUP ------ - -The *setup* sub-command creates an integration point for *Travis CI*, enabling -galaxy.ansible.com to receive notifications from *Travis* on build completion. -Requires the user first authenticate with galaxy.ansible.com using the *login* -subcommand. - -USAGE -~~~~~ - -$ ansible-galaxy setup [options] source github_user github_repo secret - -* Use *travis* as the source value. In the future additional source values may - be added. - -* Provide your *Travis* user token as the secret. The token is not stored by - galaxy.ansible.com. A hash is created using github_user, github_repo - and your token. The hash value is what actually gets stored. - -OPTIONS -~~~~~~~ - -*-c*, *--ignore-certs*:: - -Ignore TLS certificate errors. - -*-s*, *--server*:: - -Override the default server https://galaxy.ansible.com. - ---list:: - -Show your configured integrations. Provides the ID of each integration -which can be used with the remove option. - ---remove:: - -Remove a specific integration. Provide the ID of the integration to -be removed. - -AUTHOR ------- - -Ansible was originally written by Michael DeHaan. See the AUTHORS file -for a complete list of contributors. - - -COPYRIGHT ---------- - -Copyright © 2014, Michael DeHaan - -Ansible is released under the terms of the GPLv3 License. - - -SEE ALSO --------- - -*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-playbook*(1), *ansible-vault*(1) - -Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: diff --git a/docs/man/man1/ansible-playbook.1.asciidoc.in b/docs/man/man1/ansible-playbook.1.asciidoc.in deleted file mode 100644 index 3360c0d454a..00000000000 --- a/docs/man/man1/ansible-playbook.1.asciidoc.in +++ /dev/null @@ -1,275 +0,0 @@ -ansible-playbook(1) -=================== -:doctype: manpage -:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands - -NAME ----- -ansible-playbook - run an ansible playbook - - -SYNOPSIS --------- -ansible-playbook ... [options] - - -DESCRIPTION ------------ - -*Ansible playbooks* are a configuration and multinode deployment -system. Ansible-playbook is the tool used to run them. See the -project home page (link below) for more information. - - -ARGUMENTS ---------- - -*filename.yml*:: - -The names of one or more YAML format files to run as ansible playbooks. - - -OPTIONS -------- - -*-b*, *--become*:: - -Use privilege escalation (specific one depends on become_method), -this does not imply prompting for passwords. - -*-K*, *--ask-become-pass*:: - -Ask for privilege escalation password. - -*-k*, *--ask-pass*:: - -Prompt for the connection password, if it is needed for the transport used. -For example, using ssh and not having a key-based authentication with ssh-agent. - -*--ask-su-pass*:: - -Prompt for su password, used with --su (deprecated, use become). - -*--ask-sudo-pass*:: - -Prompt for the password to use with --sudo, if any (deprecated, use become). - -*--ask-vault-pass*:: - -Prompt for vault password. - -*-C*, *--check*:: - -Do not make any changes on the remote system, but test resources to see what might -have changed. Note this can not scan all possible resource types and is only -a simulation. - -*-c* 'CONNECTION', *--connection=*'CONNECTION':: - -Connection type to use. Most common options are 'paramiko' (SSH), 'ssh', 'winrm' -and 'local'. 'local' is mostly useful for crontab or kickstarts. - -*-D*, *--diff*:: - -When changing any templated files, show the unified diffs of how they changed. When -used with --check, shows how the files would have changed if --check were not used. - -*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS':: - -Extra variables to inject into a playbook, in key=value key=value format or -as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify -the file preceded by @ (e.g. @vars.yml). - -*--flush-cache*:: - -Clear the fact cache. - -*--force-handlers*:: - -Run handlers even if a task fails. - -*-f* 'NUM', *--forks=*'NUM':: - -Level of parallelism. 'NUM' is specified as an integer, the default is 5. - -*-h*, *--help*:: - -Show help page and exit. - -*-i* 'PATH', *--inventory=*'PATH':: - -The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'. -Alternatively, you can use a comma-separated list of hosts or a single host with a trailing comma 'host,'. - -*-l* 'SUBSET', *--limit=*'SUBSET':: - -Further limits the selected host/group patterns. -You can prefix it with '~' to indicate that the pattern is a regex. - -*--list-hosts*:: - -Outputs a list of matching hosts; does not execute anything else. - -*--list-tags*:: - -List all available tags; does not execute anything else. - -*--list-tasks*:: - -List all tasks that would be executed; does not execute anything else. - -*-M* 'DIRECTORY', *--module-path=*'DIRECTORY':: - -The 'DIRECTORY' search path to load modules from. The default is -'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY -environment variable. - -*--private-key=*'PRIVATE_KEY_FILE':: - -Use this file to authenticate the connection. - -*--start-at-task=*'START_AT':: - -Start the playbook at the task matching this name. - -*--step*:: - -One-step-at-a-time: confirm each task before running. - -*-S*, --su*:: - -Run operations with su (deprecated, use become). - -*-R SU-USER*, *--su-user=*'SU_USER':: - -Run operations with su as this user (default=root) (deprecated, use become). - -*-s*, *--sudo*:: - -Run the command as the user given by -u and sudo to root (deprecated, use become). - -*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...'':: - -Add the specified arguments to any sftp/scp/ssh command-line. Useful to -set a ProxyCommand to use a jump host, but any arguments that are -accepted by all three programs may be specified. - -*--sftp-extra-args=*''-f ...'':: - -Add the specified arguments to any sftp command-line. - -*--scp-extra-args=*''-l ...'':: - -Add the specified arguments to any scp command-line. - -*--ssh-extra-args=*''-R ...'':: - -Add the specified arguments to any ssh command-line. - -*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME':: - -Sudo to 'SUDO_USERNAME' default is root. (deprecated, use become). - -*--skip-tags=*'SKIP_TAGS':: - -Only run plays and tasks whose tags do not match these values. - -*--syntax-check*:: - -Look for syntax errors in the playbook, but don't run anything. - -*-t*, 'TAGS', *--tags=*'TAGS':: - -Only run plays and tasks tagged with these values. - -*-T* 'SECONDS', *--timeout=*'SECONDS':: - -Connection timeout to use when trying to talk to hosts, in 'SECONDS'. - -*-u* 'USERNAME', *--user=*'USERNAME':: - -Use this 'USERNAME' to login to the target host, instead of the current user. - -*--vault-password-file=*'VAULT_PASSWORD_FILE':: - -Vault password file. - -*-v*, *--verbose*:: - -Verbose mode, more output from successful actions will be shown. Give -up to three times for more output. - -*--version*:: - -Show program's version number and exit. - -EXIT STATUS ------------ - -*0* -- OK or no hosts matched - -*1* -- Error - -*2* -- One or more hosts failed - -*3* -- One or more hosts were unreachable - -*4* -- Parser error - -*5* -- Bad or incomplete options - -*99* -- User interrupted execution - -*250* -- Unexpected error - -ENVIRONMENT ------------ - -The following environment variables may be specified: - -ANSIBLE_INVENTORY -- Override the default ansible inventory file - -ANSIBLE_LIBRARY -- Override the default ansible module library path - -ANSIBLE_CONFIG -- Override the default ansible config file - -Many more are available for most options in ansible.cfg - - -FILES ------ - -/etc/ansible/hosts -- Default inventory file - -/usr/share/ansible/ -- Default module library - -/etc/ansible/ansible.cfg -- Config file, used if present - -~/.ansible.cfg -- User config file, overrides the default config if present - - -AUTHOR ------- - -Ansible was originally written by Michael DeHaan. See the AUTHORS file -for a complete list of contributors. - - -COPYRIGHT ---------- - -Copyright © 2012, Michael DeHaan - -Ansible is released under the terms of the GPLv3 License. - - -SEE ALSO --------- - -*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1) - -Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: diff --git a/docs/man/man1/ansible-pull.1.asciidoc.in b/docs/man/man1/ansible-pull.1.asciidoc.in deleted file mode 100644 index 84e46aadddf..00000000000 --- a/docs/man/man1/ansible-pull.1.asciidoc.in +++ /dev/null @@ -1,238 +0,0 @@ -ansible(1) -========= -:doctype: manpage -:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands - - -NAME ----- -ansible-pull - pull playbooks from VCS server and run them using this machine as the target. - - -SYNOPSIS --------- -ansible-pull -U URL [options] [ ] - - -DESCRIPTION ------------ - -*Ansible* is an extra-simple tool/framework/API for doing \'remote things'. - -Use ansible-pull to set up a remote copy of ansible on each managed -node, each set to run via cron and update playbook source via -a source repository. This inverts the default *push* architecture of -ansible into a *pull* architecture, which has near-limitless scaling -potential. - -The setup playbook can be tuned to change the cron frequency, logging -locations, and parameters to ansible-pull. - -This is useful both for extreme scale-out as well as periodic -remediation. Usage of the 'fetch' module to retrieve logs from -ansible-pull runs would be an excellent way to gather and analyze -remote logs from ansible-pull. - - -OPTIONAL ARGUMENT ------------------ - -*filename.yml*:: - -The name of one the YAML format files to run as an ansible playbook. This can -be a relative path within the checkout. If not provided, ansible-pull -will look for a playbook based on the host's fully-qualified domain name, on the -host hostname and finally a playbook named *local.yml*. - - -OPTIONS -------- - -*--accept-host-key*:: - -Adds the hostkey for the repo URL if not already added. - -*-b*, *--become*:: - -Use privilege escalation (specific one depends on become_method), -this does not imply prompting for passwords. - -*-K*, *--ask-become-pass*:: - -Ask for privilege escalation password. - -*-k*, *--ask-pass*:: - -Prompt for the connection password, if it is needed for the transport used. -For example, using ssh and not having a key-based authentication with ssh-agent. - -*--ask-su-pass*:: - -Prompt for su password, used with --su (deprecated, use become). - -*--ask-sudo-pass*:: - -Prompt for the password to use with --sudo, if any (deprecated, use become). - -*--ask-vault-pass*:: - -Prompt for vault password. - -*-C* 'CHECKOUT', *--checkout=*'CHECKOUT':: - -Branch/Tag/Commit to checkout. If not provided, uses default behavior of module used to check out playbook repository. - -*-d* 'DEST', *--directory=*'DEST':: - -Directory to checkout repository into. If not provided, a subdirectory of ~/.ansible/pull/ will be used. - -*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS:: - -Extra variables to inject into a playbook, in key=value key=value format or -as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify -the file preceded by @ (e.g. @vars.yml). - -*-f*, *--force*:: - -Force running of playbook even if unable to update playbook repository. This -can be useful, for example, to enforce run-time state when a network -connection may not always be up or possible. - -*--full*:: - -Do a full clone of the repository. By default ansible-pull will do a shallow clone based on the last revision. - -*-h*, *--help*:: - -Show the help message and exit. - -*-i* 'PATH', *--inventory=*'PATH':: - -The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'. -Alternatively you can use a comma separated list of hosts or single host with traling comma 'host,'. - -*--private-key=*'PRIVATE_KEY_FILE':: - -Use this file to authenticate the connection. - -*-m* 'NAME', *--module-name=*'NAME':: - -Module used to checkout playbook repository. Defaults to git. - -*-o*, *--only-if-changed*:: - -Only run the playbook if the repository has been updated. - -*--purge*:: - -Purge the checkout after the playbook is run. - -*-s* 'SLEEP', *--sleep=*'SLEEP':: - -Sleep for random interval (between 0 and SLEEP number of seconds) before starting. This is a useful way to disperse git requests. - -*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...'':: - -Add the specified arguments to any sftp/scp/ssh command-line. Useful to -set a ProxyCommand to use a jump host, but any arguments that are -accepted by all three programs may be specified. - -*--sftp-extra-args=*''-f ...'':: - -Add the specified arguments to any sftp command-line. - -*--scp-extra-args=*''-l ...'':: - -Add the specified arguments to any scp command-line. - -*--ssh-extra-args=*''-R ...'':: - -Add the specified arguments to any ssh command-line. - -*-t* 'TAGS', *--tags=*'TAGS':: - -Only run plays and tasks tagged with these values. - -*-U* 'URL', *--url=*'URL':: - -URL of the playbook repository to checkout. - -*--vault-password-file=*'VAULT_PASSWORD_FILE':: - -Vault password file. - -*--clean*:: - -Modified files in the working repository will be discarded. - -*--track-subs*:: - -Submodules will track the latest changes. - -*-v*, *--verbose*:: - -Pass -vvv to ansible-playbook. - - -INVENTORY ---------- - -Ansible stores the hosts it can potentially operate on in an inventory. -This can be an ini-like file, a script, directory or a list. -The ini syntax is one host per line. Groups headers are allowed and -are included on their own line, enclosed in square brackets that start the line. - -Ranges of hosts are also supported. For more information and -additional options, see the documentation on http://docs.ansible.com/. - - -ENVIRONMENT ------------ - -The following environment variables may be specified. - -ANSIBLE_INVENTORY -- Override the default ansible inventory file - -ANSIBLE_LIBRARY -- Override the default ansible module library path - -ANSIBLE_CONFIG -- Override the default ansible config file - -Many more are available for most options in ansible.cfg - - -FILES ------ - -/etc/ansible/hosts -- Default inventory file - -/usr/share/ansible/ -- Default module library - -/etc/ansible/ansible.cfg -- Config file, used if present - -~/.ansible.cfg -- User config file, overrides the default config if present - - -AUTHOR ------- - -Ansible was originally written by Michael DeHaan. -See the AUTHORS file for a complete list of contributors. - - -COPYRIGHT ---------- - -Copyright © 2012, Michael DeHaan -Ansible is released under the terms of the GPLv3 License. - - -SEE ALSO --------- - -*ansible*(1) *ansible-playbook*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1) - -Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: diff --git a/docs/man/man1/ansible-vault.1.asciidoc.in b/docs/man/man1/ansible-vault.1.asciidoc.in deleted file mode 100644 index 1c5396afa02..00000000000 --- a/docs/man/man1/ansible-vault.1.asciidoc.in +++ /dev/null @@ -1,155 +0,0 @@ -ansible-vault(1) -================ -:doctype: manpage -:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands - -NAME ----- -ansible-vault - manage encrypted ansible vars files (YAML). - - -SYNOPSIS --------- -ansible-vault [create|decrypt|edit|encrypt|rekey] [--help] [options] file_name - - -DESCRIPTION ------------ - -*ansible-vault* can encrypt any structured data file used by Ansible. -This can include *group_vars/* or *host_vars/* inventory variables, -variables loaded by *include_vars* or *vars_files*, or variable files -passed on the ansible-playbook command line with *-e @file.yml* or *-e @file.json*. -Role variables and defaults are also included! - -Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault. -If you’d like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted. - -The password used with vault currently must be the same for all files you wish to use together at the same time. - -COMMON OPTIONS --------------- - -The following options are available to all sub-commands: - -*--vault-password-file=*'FILE':: - -A file containing the vault password to be used during the encryption/decryption -steps. Be sure to keep this file secured if it is used. If the file is executable, -it will be run and its standard output will be used as the password. - -*--new-vault-password-file=*'FILE':: - -A file containing the new vault password to be used when rekeying a -file. Be sure to keep this file secured if it is used. If the file -is executable, it will be run and its standard output will be used as -the password. - -*-h*, *--help*:: - -Show a help message related to the given sub-command. - - -If '--vault-password-file' is not supplied ansible-vault will automatically prompt for passwords as required. - - -CREATE ------- - -*$ ansible-vault create [options] FILE* - -The *create* sub-command is used to initialize a new encrypted file. - -After providing a password, the tool will launch whatever editor you have defined -with $EDITOR, and defaults to vi. Once you are done with the editor session, the -file will be saved as encrypted data. - -The default cipher is AES (which is shared-secret based). - -EDIT ----- - -*$ ansible-vault edit [options] FILE* - -The *edit* sub-command is used to modify a file which was previously encrypted using ansible-vault. - -This command will decrypt the file to a temporary file and allow you to edit the file, -saving it back when done and removing the temporary file. - - -REKEY ------ - -*$ ansible-vault rekey [options] FILE_1 [FILE_2, ..., FILE_N]* - -The *rekey* command is used to change the password on a vault-encrypted files. -This command can update multiple files at once. - - -ENCRYPT -------- - -*$ ansible-vault encrypt [options] FILE_1 [FILE_2, ..., FILE_N]* - -The *encrypt* sub-command is used to encrypt pre-existing data files. -As with the *rekey* command, you can specify multiple files in one command. - -The *encrypt* command accepts an *--output FILENAME* option to determine where -encrypted output is stored. With this option, input is read from the (at most one) -filename given on the command line; if no input file is given, input is read from stdin. -Either the input or the output file may be given as '-' for stdin and stdout respectively. -If neither input nor output file is given, the command acts as a filter, -reading plaintext from stdin and writing it to stdout. - -Thus any of the following invocations can be used: - -*$ ansible-vault encrypt* - -*$ ansible-vault encrypt --output OUTFILE* - -*$ ansible-vault encrypt INFILE --output OUTFILE* - -*$ echo secret|ansible-vault encrypt --output OUTFILE* - -Reading from stdin and writing only encrypted output is a good way to prevent -sensitive data from ever hitting disk (either interactively or from a script). - -DECRYPT -------- - -*$ ansible-vault decrypt [options] FILE_1 [FILE_2, ..., FILE_N]* - -The *decrypt* sub-command is used to remove all encryption from data files. -The files will be stored as plain-text YAML once again, so be sure that you do not run this -command on data files with active passwords or other sensitive data. -In most cases, users will want to use the *edit* sub-command to modify the files securely. - -As with *encrypt*, the *decrypt* subcommand also accepts the *--output FILENAME* -option to specify where plaintext output is stored, and stdin/stdout is handled -as described above. - -AUTHOR ------- - -Ansible was originally written by Michael DeHaan. See the AUTHORS file -for a complete list of contributors. - - -COPYRIGHT ---------- - -Copyright © 2014, Michael DeHaan - -Ansible is released under the terms of the GPLv3 License. - - -SEE ALSO --------- - -*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-playbook*(1), *ansible-galaxy*(1) - -Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: diff --git a/docs/man/man1/ansible.1.asciidoc.in b/docs/man/man1/ansible.1.asciidoc.in deleted file mode 100644 index bc704692a76..00000000000 --- a/docs/man/man1/ansible.1.asciidoc.in +++ /dev/null @@ -1,260 +0,0 @@ -ansible(1) -========= -:man source: Ansible -:man version: %VERSION% -:man manual: System administration commands - -NAME ----- -ansible - run a task on a target host(s) - - -SYNOPSIS --------- -ansible [-m module_name] [-a args] [options] - - -DESCRIPTION ------------ - -*Ansible* is an extra-simple tool/framework/API for doing \'remote things'. -This is the adhoc command that allows for a \'single task playbook' run. - - -ARGUMENTS ---------- - -*host-pattern*:: - -A name of a group in the inventory, a shell-like glob selecting -hosts in inventory or any combination of the two separated by commas. - -OPTIONS -------- - -*-a* \'_ARGUMENTS_', *--args=*\'_ARGUMENTS_':: - -The 'ARGUMENTS' to pass to the module. - -*-b*, *--become*:: - -Use privilege escalation (specific one depends on become_method), -this does not imply prompting for passwords. - -*-K*, *--ask-become-pass*:: - -Ask for privilege escalation password. - -*-k*, *--ask-pass*:: - -Prompt for the connection password, if it is needed for the transport used. -For example, using ssh and not having a key-based authentication with ssh-agent. - -*--ask-su-pass*:: - -Prompt for su password, used with --su (deprecated, use become). - -*--ask-sudo-pass*:: - -Prompt for the password to use with --sudo, if any (deprecated, use become). - -*--ask-vault-pass*:: - -Prompt for vault password. - -*-B* 'NUM', *--background=*'NUM':: - -Run commands in the background, killing the task after 'NUM' seconds. - -*--become-method=*'BECOME_METHOD':: - -Privilege escalation method to use (default=sudo), -valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu ] - -*--become-user=*'BECOME_USER':: - -Run operations as this user (default=root). - -*-C*, *--check*:: - -Do not make any changes on the remote system, but test resources to see what might -have changed. Note this can not scan all possible resource types and is only -a simulation. - -*-c* 'CONNECTION', *--connection=*'CONNECTION':: - -Connection type to use. Most common options are 'paramiko' (SSH), 'ssh', 'winrm' -and 'local'. 'local' is mostly useful for crontab or kickstarts. - -*-e* 'EXTRA_VARS, *--extra-vars=*'EXTRA_VARS':: - -Extra variables to inject into a playbook, in key=value key=value format or -as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify -the file preceded by @ (e.g. @vars.yml). - -*-f* 'NUM', *--forks=*'NUM':: - -Level of parallelism. 'NUM' is specified as an integer, the default is 5. - -*-h*, *--help*:: - -Show help message and exit. - -*-i* 'PATH', *--inventory=*'PATH':: - -The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'. -Alternatively you can use a comma separated list of hosts or single host with trailing comma 'host,'. - -*-l* 'SUBSET', *--limit=*'SUBSET':: - -Further limits the selected host/group patterns. -You can prefix it with '~' to indicate that the pattern is a regex. - -*--list-hosts*:: - -Outputs a list of matching hosts; does not execute anything else. - -*-m* 'NAME', *--module-name=*'NAME':: - -Execute the module called 'NAME'. - -*-M* 'DIRECTORY', *--module-path=*'DIRECTORY':: - -The 'DIRECTORY' search path to load modules from. The default is -'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY -environment variable. - -*-o*, *--one-line*:: - -Try to output everything on one line. - -*-P* 'NUM', *--poll=*'NUM':: - -Poll a background job every 'NUM' seconds. Requires *-B*. - -*--private-key=*'PRIVATE_KEY_FILE':: - -Use this file to authenticate the connection. - -*-S*, *--su*:: - -Run operations with su (deprecated, use become). - -*-R* 'SU_USER', *--su-user=*'SU_USER':: - -Run operations with su as this user (default=root) (deprecated, use become). - -*-s*, *--sudo*:: - -Run the command as the user given by -u and sudo to root (deprecated, use become). - -*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...'':: - -Add the specified arguments to any sftp/scp/ssh command-line. Useful to -set a ProxyCommand to use a jump host, but any arguments that are -accepted by all three programs may be specified. - -*--sftp-extra-args=*''-f ...'':: - -Add the specified arguments to any sftp command-line. - -*--scp-extra-args=*''-l ...'':: - -Add the specified arguments to any scp command-line. - -*--ssh-extra-args=*''-R ...'':: - -Add the specified arguments to any ssh command-line. - -*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME':: - -Sudo to 'SUDO_USERNAME' default is root. (deprecated, use become). - -*-t* 'DIRECTORY', *--tree=*'DIRECTORY':: - -Save contents in this output 'DIRECTORY', with the results saved in a -file named after each host. - -*-T* 'SECONDS', *--timeout=*'SECONDS':: - -Connection timeout to use when trying to talk to hosts, in 'SECONDS'. - -*-u* 'USERNAME', *--user=*'USERNAME':: - -Use this 'USERNAME' to login to the target host, instead of the current user. - -*--vault-password-file=*'VAULT_PASSWORD_FILE':: - -A file containing the vault password to be used during the decryption of vault encrypted files. -Be sure to keep this file secured if it is used. If the file is executable, -it will be run and its standard output will be used as the password. - -*-v*, *--verbose*:: - -Verbose mode, more output from successful actions will be shown. -Give up to three times for more output. - -*--version*:: - -Show program version number and exit. - -INVENTORY ---------- - -Ansible stores the hosts it can potentially operate on in an inventory. -This can be an ini-like file, a script, directory or a list. -The ini syntax is one host per line. Groups headers are allowed and -are included on their own line, enclosed in square brackets that start the line. - -Ranges of hosts are also supported. For more information and -additional options, see the documentation on http://docs.ansible.com/. - - -ENVIRONMENT ------------ - -The following environment variables may be specified. - -ANSIBLE_INVENTORY -- Override the default ansible inventory file - -ANSIBLE_LIBRARY -- Override the default ansible module library path - -ANSIBLE_CONFIG -- Override the default ansible config file - -Many more are available for most options in ansible.cfg - - -FILES ------ - -/etc/ansible/hosts -- Default inventory file - -/usr/share/ansible/ -- Default module library - -/etc/ansible/ansible.cfg -- Config file, used if present - -~/.ansible.cfg -- User config file, overrides the default config if present - - -AUTHOR ------- - -Ansible was originally written by Michael DeHaan. -See the AUTHORS file for a complete list of contributors. - - -COPYRIGHT ---------- - -Copyright © 2012, Michael DeHaan -Ansible is released under the terms of the GPLv3 License. - - -SEE ALSO --------- - -*ansible-playbook*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1) - -Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: diff --git a/docs/templates/man.j2 b/docs/templates/man.j2 index bb92ec2999c..cfddd85569d 100644 --- a/docs/templates/man.j2 +++ b/docs/templates/man.j2 @@ -1,6 +1,7 @@ -ansible{% if cli != 'adhoc' %}-{{cli}}{% endif %}(1) -================== -:doctype:manpage +{% set name = ('ansible' if cli == 'adhoc' else 'ansible-%s' % cli) -%} +{{name}}(1) +{{ '=' * ((name|length|int) + 3) }} +:doctype: manpage :man source: Ansible :man version: %VERSION% :man manual: System administration commands @@ -12,12 +13,12 @@ ansible{% if cli != 'adhoc' %}-{{cli}}{% endif %} - {{short_desc|default('')}} SYNOPSIS -------- -{{ usage }} +{{ usage|replace('%prog', name) }} DESCRIPTION ----------- -{{ long_desc }} +*{{name}}* {{ long_desc|default('', True)|wordwrap }} {% if arguments %} @@ -25,13 +26,24 @@ ARGUMENTS --------- {% for arg in arguments %} -{{ arg['name'] }} +{{ arg }} -{{ arg['desc'] }} +{{ (arguments[arg]|default(' '))|wordwrap }} {% endfor %} {% endif %} +{% if actions %} +ACTIONS +------- + +{% for action in actions %} +{{ action }} + +{{ (actions[action]|default(' '))|wordwrap}} + +{% endfor %} +{% endif %} OPTIONS ------- @@ -41,7 +53,7 @@ OPTIONS {{ option['desc'] }} {% endfor %} -{% if inv_opts %} +{% if inventory %} INVENTORY --------- @@ -55,11 +67,11 @@ ENVIRONMENT The following environment variables may be specified. -{% if inv_opts %} +{% if inventory %} ANSIBLE_INVENTORY -- Override the default ansible inventory file {% endif %} -{% if run_opts %} +{% if library %} ANSIBLE_LIBRARY -- Override the default ansible module library path {% endif %} @@ -71,7 +83,7 @@ Many more are available for most options in ansible.cfg FILES ----- -{% if inv_opts %} +{% if inventory %} /etc/ansible/hosts -- Default inventory file {% endif %} @@ -90,7 +102,7 @@ See the AUTHORS file for a complete list of contributors. COPYRIGHT --------- -Copyright © 2017 Red Hat, Inc. +Copyright © 2017 Red Hat, Inc | Ansible. Ansible is released under the terms of the GPLv3 License. @@ -100,5 +112,6 @@ SEE ALSO {% for other in cli_list|sort %}{% if other != cli %}*ansible{% if other != 'adhoc' %}-{{other}}{% endif %}*(1){% if not loop.last %}, {% endif %}{% endif %}{% endfor %} Extensive documentation is available in the documentation site: -. IRC and mailing list info can be found -in file CONTRIBUTING.md, available in: +. +IRC and mailing list info can be found in file CONTRIBUTING.md, +available in: diff --git a/docs/templates/playbooks_keywords.rst.j2 b/docs/templates/playbooks_keywords.rst.j2 index f55bc2afc5b..b072bbc05e4 100644 --- a/docs/templates/playbooks_keywords.rst.j2 +++ b/docs/templates/playbooks_keywords.rst.j2 @@ -5,6 +5,8 @@ Here we list the common playbook objects and their directives. Note that not all directives affect the object itself and might just be there to be inherited by other contained objects. Aliases for the directives are not reflected here, nor are mutable ones, for example `action` in task can be substituted by the name of any module plugin. +Be aware that this reflects the 'current development branch' and that the keywords do not have 'version_added' information. + .. contents:: :local: :depth: 1 diff --git a/lib/ansible/cli/__init__.py b/lib/ansible/cli/__init__.py index aa3c8b26f6b..b513c042dc4 100644 --- a/lib/ansible/cli/__init__.py +++ b/lib/ansible/cli/__init__.py @@ -93,7 +93,7 @@ class InvalidOptsParser(SortedOptParser): class CLI(with_metaclass(ABCMeta, object)): ''' code behind bin/ansible* programs ''' - VALID_ACTIONS = ['No Actions'] + VALID_ACTIONS = [] _ITALIC = re.compile(r"I\(([^)]+)\)") _BOLD = re.compile(r"B\(([^)]+)\)") @@ -283,7 +283,8 @@ 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, desc=None): + 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 ''' # base opts @@ -665,51 +666,3 @@ class CLI(with_metaclass(ABCMeta, object)): 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 diff --git a/lib/ansible/cli/adhoc.py b/lib/ansible/cli/adhoc.py index 76b9d881b29..7b866a46c65 100644 --- a/lib/ansible/cli/adhoc.py +++ b/lib/ansible/cli/adhoc.py @@ -46,7 +46,9 @@ except ImportError: ######################################################## class AdHocCLI(CLI): - ''' Ad-hoc Ansible allows you to define and run a single task 'playbook' against a set of hosts ''' + ''' is an extra-simple tool/framework/API for doing 'remote things'. + this command 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 ''' diff --git a/lib/ansible/cli/console.py b/lib/ansible/cli/console.py index 5bf9d9e84d0..2116ffb79ac 100644 --- a/lib/ansible/cli/console.py +++ b/lib/ansible/cli/console.py @@ -58,8 +58,13 @@ except ImportError: class ConsoleCLI(CLI, cmd.Cmd): + ''' a REPL that allows for running ad-hoc tasks against a chosen inventory (based on dominis' ansible-shell).''' modules = [] + ARGUMENTS = { + 'host-pattern': 'A name of a group in the inventory, a shell-like glob ' + 'selecting hosts in inventory or any combination of the two separated by commas.', + } def __init__(self, args): diff --git a/lib/ansible/cli/doc.py b/lib/ansible/cli/doc.py index d5cc670bf91..b6233cee786 100644 --- a/lib/ansible/cli/doc.py +++ b/lib/ansible/cli/doc.py @@ -40,7 +40,10 @@ except ImportError: class DocCLI(CLI): - """ Doc command line class """ + ''' displays information on modules installed in Ansible libraries. + It displays a terse listing of plugins and their short descriptions, + provides a printout of their DOCUMENTATION strings, + and it can create a short "snippet" which can be pasted into a playbook. ''' def __init__(self, args): diff --git a/lib/ansible/cli/galaxy.py b/lib/ansible/cli/galaxy.py index 3fea680c439..8554b68c402 100644 --- a/lib/ansible/cli/galaxy.py +++ b/lib/ansible/cli/galaxy.py @@ -50,6 +50,7 @@ except ImportError: class GalaxyCLI(CLI): + '''command to manage Ansible roles in shared repostories, the default of which is Ansible Galaxy *https://galaxy.ansible.com*.''' SKIP_INFO_KEYS = ("name", "description", "readme_html", "related", "summary_fields", "average_aw_composite", "average_aw_score", "url" ) VALID_ACTIONS = ("delete", "import", "info", "init", "install", "list", "login", "remove", "search", "setup") @@ -59,20 +60,10 @@ class GalaxyCLI(CLI): self.galaxy = None super(GalaxyCLI, self).__init__(args) - def parse(self): - ''' create an options parser for bin/ansible ''' + def set_action(self): - self.parser = CLI.base_parser( - usage = "usage: %%prog [%s] [--help] [options] ..." % "|".join(self.VALID_ACTIONS), - epilog = "\nSee '%s --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0]) - ) + super(GalaxyCLI, self).set_action() - self.set_action() - - # common - self.parser.add_option('-s', '--server', dest='api_server', default=C.GALAXY_SERVER, help='The API server destination') - self.parser.add_option('-c', '--ignore-certs', action='store_true', dest='ignore_certs', default=C.GALAXY_IGNORE_CERTS, - help='Ignore SSL certificate validation errors.') # specific to actions if self.action == "delete": @@ -135,6 +126,20 @@ class GalaxyCLI(CLI): if self.action in ("init","install"): self.parser.add_option('-f', '--force', dest='force', action='store_true', default=False, help='Force overwriting an existing role') + def parse(self): + ''' create an options parser for bin/ansible ''' + + self.parser = CLI.base_parser( + usage = "usage: %%prog [%s] [--help] [options] ..." % "|".join(self.VALID_ACTIONS), + epilog = "\nSee '%s --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0]) + ) + + # common + self.parser.add_option('-s', '--server', dest='api_server', default=C.GALAXY_SERVER, help='The API server destination') + self.parser.add_option('-c', '--ignore-certs', action='store_true', dest='ignore_certs', default=C.GALAXY_IGNORE_CERTS, + help='Ignore SSL certificate validation errors.') + self.set_action() + super(GalaxyCLI, self).parse() display.verbosity = self.options.verbosity @@ -182,8 +187,7 @@ class GalaxyCLI(CLI): def execute_init(self): """ - Executes the init action, which creates the skeleton framework - of a role that complies with the galaxy metadata format. + creates the skeleton framework of a role that complies with the galaxy metadata format. """ init_path = self.get_opt('init_path', './') @@ -255,9 +259,7 @@ class GalaxyCLI(CLI): def execute_info(self): """ - Executes the info action. This action prints out detailed - information about an installed role as well as info available - from the galaxy API. + prints out detailed information about an installed role as well as info available from the galaxy API. """ if len(self.args) == 0: @@ -304,10 +306,8 @@ class GalaxyCLI(CLI): def execute_install(self): """ - Executes the installation action. The args list contains the - roles to be installed, unless -f was specified. The list of roles - can be a name (which will be downloaded via the galaxy API and github), - or it can be a local .tar.gz file. + uses the args list of roles to be installed, unless -f was specified. The list of roles + can be a name (which will be downloaded via the galaxy API and github), or it can be a local .tar.gz file. """ role_file = self.get_opt("role_file", None) @@ -432,8 +432,7 @@ class GalaxyCLI(CLI): def execute_remove(self): """ - Executes the remove action. The args list contains the list - of roles to be removed. This list can contain more than one role. + removes the list of roles passed as arguments from the local system. """ if len(self.args) == 0: @@ -453,10 +452,7 @@ class GalaxyCLI(CLI): def execute_list(self): """ - Executes the list action. The args list can contain zero - or one role. If one is specified, only that role will be - shown, otherwise all roles in the specified directory will - be shown. + lists the roles installed on the local system or matches a single role passed as an argument. """ if len(self.args) > 1: @@ -500,6 +496,7 @@ class GalaxyCLI(CLI): return 0 def execute_search(self): + ''' searches for roles on the Ansible Galaxy server''' page_size = 1000 search = None @@ -544,7 +541,7 @@ class GalaxyCLI(CLI): def execute_login(self): """ - Verify user's identify via Github and retrieve an auth token from Galaxy. + verify user's identify via Github and retrieve an auth token from Ansible Galaxy. """ # Authenticate with github and retrieve a token if self.options.token is None: @@ -567,9 +564,7 @@ class GalaxyCLI(CLI): return 0 def execute_import(self): - """ - Import a role into Galaxy - """ + """ used to import a role into Ansible Galaxy """ colors = { 'INFO': 'normal', @@ -625,9 +620,7 @@ class GalaxyCLI(CLI): return 0 def execute_setup(self): - """ - Setup an integration from Github or Travis - """ + """ Setup an integration from Github or Travis for Ansible Galaxy roles""" if self.options.setup_list: # List existing integration secrets @@ -664,9 +657,7 @@ class GalaxyCLI(CLI): return 0 def execute_delete(self): - """ - Delete a role from galaxy.ansible.com - """ + """ Delete a role from Ansible Galaxy. """ if len(self.args) < 2: raise AnsibleError("Missing one or more arguments. Expected: github_user github_repo") diff --git a/lib/ansible/cli/playbook.py b/lib/ansible/cli/playbook.py index 349841159e6..679396c85c1 100644 --- a/lib/ansible/cli/playbook.py +++ b/lib/ansible/cli/playbook.py @@ -44,7 +44,9 @@ except ImportError: #--------------------------------------------------------------------------------------------------- class PlaybookCLI(CLI): - ''' code behind ansible playbook cli''' + ''' the tool to run *Ansible playbooks*, which are a configuration and multinode deployment system. + See the project home page (https://docs.ansible.com) for more information. ''' + def parse(self): diff --git a/lib/ansible/cli/pull.py b/lib/ansible/cli/pull.py index ccc9eae89ef..105992e8307 100644 --- a/lib/ansible/cli/pull.py +++ b/lib/ansible/cli/pull.py @@ -44,7 +44,16 @@ except ImportError: ######################################################## class PullCLI(CLI): - ''' code behind ansible ad-hoc cli''' + ''' is used to up a remote copy of ansible on each managed node, + each set to run via cron and update playbook source via a source repository. + This inverts the default *push* architecture of ansible into a *pull* architecture, + which has near-limitless scaling potential. + + The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible-pull. + This is useful both for extreme scale-out as well as periodic remediation. + Usage of the 'fetch' module to retrieve logs from ansible-pull runs would be an + excellent way to gather and analyze remote logs from ansible-pull. + ''' DEFAULT_REPO_TYPE = 'git' DEFAULT_PLAYBOOK = 'local.yml' @@ -53,12 +62,18 @@ class PullCLI(CLI): 2: 'File is not readable' } SUPPORTED_REPO_MODULES = ['git'] + ARGUMENTS = { + 'playbook.yml': 'The name of one the YAML format files to run as an Ansible playbook.' + 'This can be a relative path within the checkout. By default, Ansible will' + "look for a playbook based on the host's fully-qualified domain name," + 'on the host hostname and finally a playbook named *local.yml*.', + } def parse(self): ''' create an options parser for bin/ansible ''' self.parser = CLI.base_parser( - usage='%prog -U [options]', + usage='%prog -U [options] []', connect_opts=True, vault_opts=True, runtask_opts=True, @@ -70,22 +85,18 @@ class PullCLI(CLI): ) # options unique to pull - self.parser.add_option('--purge', default=False, action='store_true', - help='purge checkout after playbook run') + self.parser.add_option('--purge', default=False, action='store_true', help='purge checkout after playbook run') self.parser.add_option('-o', '--only-if-changed', dest='ifchanged', default=False, action='store_true', help='only run the playbook if the repository has been updated') self.parser.add_option('-s', '--sleep', dest='sleep', default=None, help='sleep for random interval (between 0 and n number of seconds) before starting. This is a useful way to disperse git requests') self.parser.add_option('-f', '--force', dest='force', default=False, action='store_true', help='run the playbook even if the repository could not be updated') - self.parser.add_option('-d', '--directory', dest='dest', default=None, - help='directory to checkout repository to') - self.parser.add_option('-U', '--url', dest='url', default=None, - help='URL of the playbook repository') - self.parser.add_option('--full', dest='fullclone', action='store_true', - help='Do a full clone, instead of a shallow one.') + self.parser.add_option('-d', '--directory', dest='dest', default=None, help='directory to checkout repository to') + self.parser.add_option('-U', '--url', dest='url', default=None, help='URL of the playbook repository') + self.parser.add_option('--full', dest='fullclone', action='store_true', help='Do a full clone, instead of a shallow one.') self.parser.add_option('-C', '--checkout', dest='checkout', - help='branch/tag/commit to checkout. ' 'Defaults to behavior of repository module.') + help='branch/tag/commit to checkout. Defaults to behavior of repository module.') self.parser.add_option('--accept-host-key', default=False, dest='accept_host_key', action='store_true', help='adds the hostkey for the repo url if not already added') self.parser.add_option('-m', '--module-name', dest='module_name', default=self.DEFAULT_REPO_TYPE, @@ -96,8 +107,7 @@ class PullCLI(CLI): self.parser.add_option('--clean', dest='clean', default=False, action='store_true', help='modified files in the working repository will be discarded') self.parser.add_option('--track-subs', dest='tracksubs', default=False, action='store_true', - help='submodules will track the latest changes' - ' This is equivalent to specifying the --remote flag to git submodule update') + help='submodules will track the latest changes. This is equivalent to specifying the --remote flag to git submodule update') # for pull we don't wan't a default self.parser.set_defaults(inventory=None) diff --git a/lib/ansible/cli/vault.py b/lib/ansible/cli/vault.py index 9a96e9e1a35..61f3e0f126f 100644 --- a/lib/ansible/cli/vault.py +++ b/lib/ansible/cli/vault.py @@ -36,7 +36,17 @@ except ImportError: class VaultCLI(CLI): - """ Vault command line class """ + ''' can encrypt any structured data file used by Ansible. + This can include *group_vars/* or *host_vars/* inventory variables, + variables loaded by *include_vars* or *vars_files*, or variable files + passed on the ansible-playbook command line with *-e @file.yml* or *-e @file.json*. + Role variables and defaults are also included! + + Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault. + If you'd like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted. + + The password used with vault currently must be the same for all files you wish to use together at the same time. + ''' VALID_ACTIONS = ("create", "decrypt", "edit", "encrypt", "encrypt_string", "rekey", "view") @@ -51,16 +61,9 @@ class VaultCLI(CLI): self.encrypt_string_read_stdin = False super(VaultCLI, self).__init__(args) - def parse(self): + def set_action(self): - self.parser = CLI.base_parser( - vault_opts=True, - usage = "usage: %%prog [%s] [options] [vaultfile.yml]" % "|".join(self.VALID_ACTIONS), - desc = "encryption/decryption utility for Ansbile data files", - epilog = "\nSee '%s --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0]) - ) - - self.set_action() + super(VaultCLI, self).set_action() # options specific to self.actions if self.action == "create": @@ -88,6 +91,17 @@ class VaultCLI(CLI): elif self.action == "rekey": self.parser.set_usage("usage: %prog rekey [options] file_name") + def parse(self): + + self.parser = CLI.base_parser( + vault_opts=True, + usage = "usage: %%prog [%s] [options] [vaultfile.yml]" % "|".join(self.VALID_ACTIONS), + desc = "encryption/decryption utility for Ansbile data files", + epilog = "\nSee '%s --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0]) + ) + + self.set_action() + super(VaultCLI, self).parse() display.verbosity = self.options.verbosity @@ -162,6 +176,7 @@ class VaultCLI(CLI): os.umask(old_umask) def execute_encrypt(self): + ''' encrypt the supplied file using the provided vault secret ''' if len(self.args) == 0 and sys.stdin.isatty(): display.display("Reading plaintext input from stdin", stderr=True) @@ -191,6 +206,7 @@ class VaultCLI(CLI): return yaml_ciphertext def execute_encrypt_string(self): + ''' encrypt the supplied string using the provided vault secret ''' b_plaintext = None # Holds tuples (the_text, the_source_of_the_string, the variable name if its provided). @@ -314,6 +330,7 @@ class VaultCLI(CLI): return output def execute_decrypt(self): + ''' decrypt the supplied file using the provided vault secret ''' if len(self.args) == 0 and sys.stdin.isatty(): display.display("Reading ciphertext input from stdin", stderr=True) @@ -325,6 +342,7 @@ class VaultCLI(CLI): display.display("Decryption successful", stderr=True) def execute_create(self): + ''' create and open a file in an editor that will be encryped with the provided vault secret when closed''' if len(self.args) > 1: raise AnsibleOptionsError("ansible-vault create can take only one filename argument") @@ -332,10 +350,12 @@ class VaultCLI(CLI): self.editor.create_file(self.args[0]) def execute_edit(self): + ''' open and decrypt an existing vaulted file in an editor, that will be encryped again when closed''' for f in self.args: self.editor.edit_file(f) def execute_view(self): + ''' open, decrypt and view an existing vaulted file using a pager using the supplied vault secret ''' for f in self.args: # Note: vault should return byte strings because it could encrypt @@ -346,6 +366,7 @@ class VaultCLI(CLI): self.pager(to_text(self.editor.plaintext(f))) def execute_rekey(self): + ''' re-encrypt a vaulted file with a new secret, the previous secret is required ''' for f in self.args: if not (os.path.isfile(f)): raise AnsibleError(f + " does not exist") diff --git a/test/sanity/pep8/legacy-files.txt b/test/sanity/pep8/legacy-files.txt index f8836f4c00a..f17dd92a293 100644 --- a/test/sanity/pep8/legacy-files.txt +++ b/test/sanity/pep8/legacy-files.txt @@ -38,14 +38,14 @@ contrib/inventory/windows_azure.py contrib/inventory/zabbix.py contrib/inventory/zone.py docs/api/conf.py +docs/bin/dump_keywords.py +docs/bin/plugin_formatter.py docs/docsite/conf.py docs/docsite/rst/conf.py examples/scripts/uptime.py hacking/cherrypick.py -hacking/dump_playbook_attributes.py hacking/get_library.py hacking/metadata-tool.py -hacking/module_formatter.py hacking/tests/gen_distribution_version_testcase.py lib/ansible/cli/__init__.py lib/ansible/cli/adhoc.py