ungleich-public/cdist
ungleich-public
/
cdist
7
3
Fork 11
Code Issues 56 Pull Requests 15 Projects Releases Wiki Activity

Cleanup options' help and cdist man page.

This commit is contained in:
Darko Poljak 2017-08-17 08:24:58 +02:00
parent eb01c5bb85
commit 982bb286f4
2 changed files with 89 additions and 112 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
cdist/argparse.py
View File

@ -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(

112
docs/src/man1/cdist.rst
View File

@ -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