From 982bb286f49e8941934654f7487ae9d24d467771 Mon Sep 17 00:00:00 2001 From: Darko Poljak Date: Thu, 17 Aug 2017 08:24:58 +0200 Subject: [PATCH] Cleanup options' help and cdist man page. --- cdist/argparse.py | 89 +++++++++++++++++-------------- docs/src/man1/cdist.rst | 112 ++++++++++++++-------------------------- 2 files changed, 89 insertions(+), 112 deletions(-) diff --git a/cdist/argparse.py b/cdist/argparse.py index 4d9dc719..9afc5a82 100644 --- a/cdist/argparse.py +++ b/cdist/argparse.py @@ -27,6 +27,17 @@ _verbosity_level = { 3: logging.DEBUG, 4: logging.TRACE, } + + +# Generate verbosity level constants: +# VERBOSE_OFF, VERBOSE_ERROR, VERBOSE_WARNING, VERBOSE_INFO, VERBOSE_VERBOSE, +# VERBOSE_DEBUG, VERBOSE_TRACE. +this_globals = globals() +for level in _verbosity_level: + const = 'VERBOSE_' + logging.getLevelName(_verbosity_level[level]) + this_globals[const] = level + + # All verbosity levels above 4 are TRACE. _verbosity_level = collections.defaultdict( lambda: logging.TRACE, _verbosity_level) @@ -87,7 +98,7 @@ def get_parsers(): parser['loglevel'] = argparse.ArgumentParser(add_help=False) parser['loglevel'].add_argument( '-q', '--quiet', - help='Quiet mode: disables logging, including WARNING and ERROR', + help='Quiet mode: disables logging, including WARNING and ERROR.', action='store_true', default=False) parser['loglevel'].add_argument( '-v', '--verbose', @@ -102,16 +113,15 @@ def get_parsers(): parser['beta'] = argparse.ArgumentParser(add_help=False) parser['beta'].add_argument( '-b', '--beta', - help=('Enable beta functionality. ' - 'Can also be enabled using CDIST_BETA env var.'), + help=('Enable beta functionality. '), action='store_true', dest='beta', - default='CDIST_BETA' in os.environ) + default=False) # Main subcommand parser parser['main'] = argparse.ArgumentParser( description='cdist ' + cdist.VERSION, parents=[parser['loglevel']]) parser['main'].add_argument( - '-V', '--version', help='Show version', action='version', + '-V', '--version', help='Show version.', action='version', version='%(prog)s ' + cdist.VERSION) parser['sub'] = parser['main'].add_subparsers( title="Commands", dest="command") @@ -136,18 +146,17 @@ def get_parsers(): parser['config_main'] = argparse.ArgumentParser(add_help=False) parser['config_main'].add_argument( '-C', '--cache-path-pattern', - help=('Specify custom cache path pattern. It can also be set ' - 'by CDIST_CACHE_PATH_PATTERN environment variable. If ' + help=('Specify custom cache path pattern. If ' 'it is not set then default hostdir is used.'), dest='cache_path_pattern', - default=os.environ.get('CDIST_CACHE_PATH_PATTERN')) + default=None) parser['config_main'].add_argument( '-c', '--conf-dir', help=('Add configuration directory (can be repeated, ' - 'last one wins)'), action='append') + 'last one wins).'), action='append') parser['config_main'].add_argument( '-i', '--initial-manifest', - help='path to a cdist manifest or \'-\' to read from stdin.', + help='Path to a cdist manifest or \'-\' to read from stdin.', dest='manifest', required=False) parser['config_main'].add_argument( '-j', '--jobs', nargs='?', @@ -160,17 +169,18 @@ def get_parsers(): const=multiprocessing.cpu_count()) parser['config_main'].add_argument( '-n', '--dry-run', - help='do not execute code', action='store_true') + help='Do not execute code.', action='store_true') parser['config_main'].add_argument( '-o', '--out-dir', - help='directory to save cdist output in', dest="out_path") + help='Directory to save cdist output in.', dest="out_path") parser['config_main'].add_argument( '-R', '--use-archiving', nargs='?', choices=('tar', 'tgz', 'tbz2', 'txz',), help=('Operate by using archiving with compression where ' 'apropriate. Supported values are: tar - tar archive, ' 'tgz - gzip tar archive (the default), ' - 'tbz2 - bzip2 tar archive and txz - lzma tar archive.'), + 'tbz2 - bzip2 tar archive and txz - lzma tar archive. ' + 'Currently in beta.'), action='store', dest='use_archiving', const='tgz') @@ -179,33 +189,33 @@ def get_parsers(): # parsing to determine implementation default parser['config_main'].add_argument( '-r', '--remote-out-dir', - help='Directory to save cdist output in on the target host', + help='Directory to save cdist output in on the target host.', dest="remote_out_path") parser['config_main'].add_argument( '--remote-copy', - help='Command to use for remote copy (should behave like scp)', + help='Command to use for remote copy (should behave like scp).', action='store', dest='remote_copy', - default=os.environ.get('CDIST_REMOTE_COPY')) + default=None) parser['config_main'].add_argument( '--remote-exec', help=('Command to use for remote execution ' - '(should behave like ssh)'), + '(should behave like ssh).'), action='store', dest='remote_exec', - default=os.environ.get('CDIST_REMOTE_EXEC')) + default=None) # Config parser['config_args'] = argparse.ArgumentParser(add_help=False) parser['config_args'].add_argument( '-A', '--all-tagged', - help=('use all hosts present in tags db'), + help=('Use all hosts present in tags db. Currently in beta.'), action="store_true", dest="all_tagged_hosts", default=False) parser['config_args'].add_argument( '-a', '--all', - help=('list hosts that have all specified tags, ' - 'if -t/--tag is specified'), + help=('List hosts that have all specified tags, ' + 'if -t/--tag is specified.'), action="store_true", dest="has_all_tags", default=False) parser['config_args'].add_argument( - 'host', nargs='*', help='host(s) to operate on') + 'host', nargs='*', help='Host(s) to operate on.') parser['config_args'].add_argument( '-f', '--file', help=('Read specified file for a list of additional hosts to ' @@ -223,12 +233,13 @@ def get_parsers(): const=multiprocessing.cpu_count()) parser['config_args'].add_argument( '-s', '--sequential', - help='operate on multiple hosts sequentially (default)', + help='Operate on multiple hosts sequentially (default).', action='store_const', dest='parallel', const=0) parser['config_args'].add_argument( '-t', '--tag', - help=('host is specified by tag, not hostname/address; ' - 'list all hosts that contain any of specified tags'), + help=('Host is specified by tag, not hostname/address; ' + 'list all hosts that contain any of specified tags. ' + 'Currently in beta.'), dest='tag', required=False, action="store_true", default=False) parser['config'] = parser['sub'].add_parser( 'config', parents=[parser['loglevel'], parser['beta'], @@ -253,7 +264,7 @@ def get_parsers(): 'add-host', parents=[parser['loglevel'], parser['beta'], parser['inventory_common']]) parser['add-host'].add_argument( - 'host', nargs='*', help='host(s) to add') + 'host', nargs='*', help='Host(s) to add.') parser['add-host'].add_argument( '-f', '--file', help=('Read additional hosts to add from specified file ' @@ -267,7 +278,7 @@ def get_parsers(): parser['inventory_common']]) parser['add-tag'].add_argument( 'host', nargs='*', - help='list of host(s) for which tags are added') + help='List of host(s) for which tags are added.') parser['add-tag'].add_argument( '-f', '--file', help=('Read additional hosts to add tags from specified file ' @@ -289,16 +300,16 @@ def get_parsers(): parser['add-tag'].add_argument( '-t', '--taglist', help=("Tag list to be added for specified host(s), comma separated" - " values"), + " values."), dest="taglist", required=False) parser['del-host'] = parser['invsub'].add_parser( 'del-host', parents=[parser['loglevel'], parser['beta'], parser['inventory_common']]) parser['del-host'].add_argument( - 'host', nargs='*', help='host(s) to delete') + 'host', nargs='*', help='Host(s) to delete.') parser['del-host'].add_argument( - '-a', '--all', help=('Delete all hosts'), + '-a', '--all', help=('Delete all hosts.'), dest='all', required=False, action="store_true", default=False) parser['del-host'].add_argument( '-f', '--file', @@ -313,10 +324,10 @@ def get_parsers(): parser['inventory_common']]) parser['del-tag'].add_argument( 'host', nargs='*', - help='list of host(s) for which tags are deleted') + help='List of host(s) for which tags are deleted.') parser['del-tag'].add_argument( '-a', '--all', - help=('Delete all tags for specified host(s)'), + help=('Delete all tags for specified host(s).'), dest='all', required=False, action="store_true", default=False) parser['del-tag'].add_argument( '-f', '--file', @@ -339,18 +350,18 @@ def get_parsers(): parser['del-tag'].add_argument( '-t', '--taglist', help=("Tag list to be deleted for specified host(s), " - "comma separated values"), + "comma separated values."), dest="taglist", required=False) parser['list'] = parser['invsub'].add_parser( 'list', parents=[parser['loglevel'], parser['beta'], parser['inventory_common']]) parser['list'].add_argument( - 'host', nargs='*', help='host(s) to list') + 'host', nargs='*', help='Host(s) to list.') parser['list'].add_argument( '-a', '--all', - help=('list hosts that have all specified tags, ' - 'if -t/--tag is specified'), + help=('List hosts that have all specified tags, ' + 'if -t/--tag is specified.'), action="store_true", dest="has_all_tags", default=False) parser['list'].add_argument( '-f', '--file', @@ -359,12 +370,12 @@ def get_parsers(): 'If no host or host file is specified then, by default, ' 'list all.'), dest='hostfile', required=False) parser['list'].add_argument( - '-H', '--host-only', help=('Suppress tags listing'), + '-H', '--host-only', help=('Suppress tags listing.'), action="store_true", dest="list_only_host", default=False) parser['list'].add_argument( '-t', '--tag', - help=('host is specified by tag, not hostname/address; ' - 'list all hosts that contain any of specified tags'), + help=('Host is specified by tag, not hostname/address; ' + 'list all hosts that contain any of specified tags.'), action="store_true", default=False) parser['inventory'].set_defaults( diff --git a/docs/src/man1/cdist.rst b/docs/src/man1/cdist.rst index 931b4a1f..c494ff57 100644 --- a/docs/src/man1/cdist.rst +++ b/docs/src/man1/cdist.rst @@ -71,11 +71,11 @@ All commands accept the following options: .. option:: -h, --help - Show the help screen + Show the help screen. .. option:: -q, --quiet - Quiet mode: disables logging, including WARNING and ERROR + Quiet mode: disables logging, including WARNING and ERROR. .. option:: -v, --verbose @@ -86,7 +86,7 @@ All commands accept the following options: .. option:: -V, --version - Show version and exit + Show version and exit. BANNER @@ -98,26 +98,24 @@ cdist posters - a must have for every office. CONFIG/INSTALL -------------- Configure/install one or more hosts. +Install command is currently in beta. .. option:: -A, --all-tagged - use all hosts present in tags db + Use all hosts present in tags db. Currently in beta. .. option:: -a, --all - list hosts that have all specified tags, if -t/--tag - is specified + List hosts that have all specified tags, if -t/--tag + is specified. .. option:: -b, --beta Enable beta functionality. - - Can also be enabled using CDIST_BETA env var. .. option:: -C CACHE_PATH_PATTERN, --cache-path-pattern CACHE_PATH_PATTERN - Sepcify custom cache path pattern. It can also be set by - CDIST_CACHE_PATH_PATTERN environment variable. If it is not set then + Sepcify custom cache path pattern. If it is not set then default hostdir is used. For more info on format see :strong:`CACHE PATH PATTERN FORMAT` below. @@ -125,11 +123,7 @@ Configure/install one or more hosts. Add a configuration directory. Can be specified multiple times. If configuration directories contain conflicting types, explorers or - manifests, then the last one found is used. Additionally this can also - be configured by setting the CDIST_PATH environment variable to a colon - delimited list of config directories. Directories given with the - --conf-dir argument have higher precedence over those set through the - environment variable. + manifests, then the last one found is used. .. option:: -f HOSTFILE, --file HOSTFILE @@ -151,7 +145,7 @@ Configure/install one or more hosts. .. option:: -i MANIFEST, --initial-manifest MANIFEST - Path to a cdist manifest or - to read from stdin + Path to a cdist manifest or - to read from stdin. .. option:: -j [JOBS], --jobs [JOBS] @@ -162,11 +156,11 @@ Configure/install one or more hosts. .. option:: -n, --dry-run - Do not execute code + Do not execute code. .. option:: -o OUT_PATH, --out-dir OUT_PATH - Directory to save cdist output in + Directory to save cdist output in. .. option:: -p [HOST_MAX], --parallel [HOST_MAX] @@ -179,29 +173,29 @@ Configure/install one or more hosts. Operate by using archiving with compression where apropriate. Supported values are: tar - tar archive, tgz - gzip tar archive (the default), tbz2 - bzip2 tar - archive and txz - lzma tar archive. - + archive and txz - lzma tar archive. Currently in beta. .. option:: -r REMOTE_OUT_PATH, --remote-out-dir REMOTE_OUT_PATH - Directory to save cdist output in on the target host + Directory to save cdist output in on the target host. .. option:: -s, --sequential - Operate on multiple hosts sequentially (default) + Operate on multiple hosts sequentially (default). .. option:: --remote-copy REMOTE_COPY - Command to use for remote copy (should behave like scp) + Command to use for remote copy (should behave like scp). .. option:: --remote-exec REMOTE_EXEC - Command to use for remote execution (should behave like ssh) + Command to use for remote execution (should behave like ssh). .. option:: -t, --tag - host is specified by tag, not hostname/address; list - all hosts that contain any of specified tags + Host is specified by tag, not hostname/address; list + all hosts that contain any of specified tags. + Currently in beta. HOSTFILE FORMAT ~~~~~~~~~~~~~~~ @@ -247,16 +241,11 @@ Add host(s) to inventory database. .. option:: host - host(s) to add + Host(s) to add. .. option:: -b, --beta - Enable beta functionalities. Beta functionalities - include inventory command with all sub-commands and - all options; config sub-command options: -j/--jobs, - -t/--tag, -a/--all. - - Can also be enabled using CDIST_BETA env var. + Enable beta functionality. .. option:: -f HOSTFILE, --file HOSTFILE @@ -265,9 +254,6 @@ Add host(s) to inventory database. host or host file is specified then, by default, read from stdin. Hostfile format is the same as config hostfile format. -.. option:: -h, --help - - show this help message and exit .. option:: -I INVENTORY_DIR, --inventory INVENTORY_DIR @@ -286,16 +272,11 @@ Add tag(s) to inventory database. .. option:: host - list of host(s) for which tags are added + List of host(s) for which tags are added. .. option:: -b, --beta - Enable beta functionalities. Beta functionalities - include inventory command with all sub-commands and - all options; config sub-command options: -j/--jobs, - -t/--tag, -a/--all. - - Can also be enabled using CDIST_BETA env var. + Enable beta functionality. .. option:: -f HOSTFILE, --file HOSTFILE @@ -328,7 +309,7 @@ Add tag(s) to inventory database. .. option:: -t TAGLIST, --taglist TAGLIST Tag list to be added for specified host(s), comma - separated values + separated values. INVENTORY DEL-HOST @@ -337,20 +318,15 @@ Delete host(s) from inventory database. .. option:: host - host(s) to delete + Host(s) to delete. .. option:: -a, --all - Delete all hosts + Delete all hosts. .. option:: -b, --beta - Enable beta functionalities. Beta functionalities - include inventory command with all sub-commands and - all options; config sub-command options: -j/--jobs, - -t/--tag, -a/--all. - - Can also be enabled using CDIST_BETA env var. + Enable beta functionality. .. option:: -f HOSTFILE, --file HOSTFILE @@ -376,20 +352,15 @@ Delete tag(s) from inventory database. .. option:: host - list of host(s) for which tags are deleted + List of host(s) for which tags are deleted. .. option:: -a, --all - Delete all tags for specified host(s) + Delete all tags for specified host(s). .. option:: -b, --beta - Enable beta functionalities. Beta functionalities - include inventory command with all sub-commands and - all options; config sub-command options: -j/--jobs, - -t/--tag, -a/--all. - - Can also be enabled using CDIST_BETA env var. + Enable beta functionality. .. option:: -f HOSTFILE, --file HOSTFILE @@ -423,7 +394,7 @@ Delete tag(s) from inventory database. .. option:: -t TAGLIST, --taglist TAGLIST Tag list to be deleted for specified host(s), comma - separated values + separated values. INVENTORY LIST @@ -432,21 +403,16 @@ List inventory database. .. option:: host - host(s) to list + Host(s) to list. .. option:: -a, --all - list hosts that have all specified tags, if -t/--tag - is specified + List hosts that have all specified tags, if -t/--tag + is specified. .. option:: -b, --beta - Enable beta functionalities. Beta functionalities - include inventory command with all sub-commands and - all options; config sub-command options: -j/--jobs, - -t/--tag, -a/--all. - - Can also be enabled using CDIST_BETA env var. + Enable beta functionality. .. option:: -f HOSTFILE, --file HOSTFILE @@ -457,7 +423,7 @@ List inventory database. .. option:: -H, --host-only - Suppress tags listing + Suppress tags listing. .. option:: -I INVENTORY_DIR, --inventory INVENTORY_DIR @@ -471,8 +437,8 @@ List inventory database. .. option:: -t, --tag - host is specified by tag, not hostname/address; list - all hosts that contain any of specified tags + Host is specified by tag, not hostname/address; list + all hosts that contain any of specified tags. SHELL