From 88ae1ebf33ffb9ae1db0d1c52422a6cf70cce85d Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Wed, 21 Jun 2017 00:02:57 +0200 Subject: [PATCH 1/3] docs: format metavars more accurately --- setup.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/setup.py b/setup.py index 1461c02f6..f2b4d9771 100644 --- a/setup.py +++ b/setup.py @@ -203,6 +203,17 @@ with open('README.rst', 'r') as fd: long_description = re.compile(r'^\.\. highlight:: \w+$', re.M).sub('', long_description) +def format_metavar(option): + if option.nargs in ('*', '...'): + return '[%s...]' % option.metavar + elif option.nargs == '?': + return '[%s]' % option.metavar + elif option.nargs is None: + return option.metavar + else: + raise ValueError('Can\'t format metavar %s, unknown nargs %s!' % (option.metavar, option.nargs)) + + class build_usage(Command): description = "generate usage for each command" @@ -284,7 +295,7 @@ class build_usage(Command): for option in parser._actions: if option.option_strings: continue - fp.write(' ' + option.metavar) + fp.write(' ' + format_metavar(option)) fp.write('\n\n') def write_options(self, parser, fp): @@ -645,11 +656,11 @@ class build_man(Command): def write_usage(self, write, parser): if any(len(o.option_strings) for o in parser._actions): - write(' ', end='') + write(' [options] ', end='') for option in parser._actions: if option.option_strings: continue - write(option.metavar, end=' ') + write(format_metavar(option), end=' ') def write_options(self, write, parser): for group in parser._action_groups: From 09d0d566a5a86ac2f032b441852747bbfacca764 Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Wed, 21 Jun 2017 00:16:06 +0200 Subject: [PATCH 2/3] docs: with-lock: convert to proper admonition --- src/borg/archiver.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 449198ea6..e00e344a2 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -3591,9 +3591,11 @@ class Archiver: for its termination, release the lock and return the user command's return code as borg's return code. - Note: if you copy a repository with the lock held, the lock will be present in - the copy, obviously. Thus, before using borg on the copy, you need to - use "borg break-lock" on it. + .. note:: + + If you copy a repository with the lock held, the lock will be present in + the copy, obviously. Thus, before using borg on the copy, you need to + use "borg break-lock" on it. """) subparser = subparsers.add_parser('with-lock', parents=[common_parser], add_help=False, description=self.do_with_lock.__doc__, From 771168a3afcb8556c35997c00ffbd4421dcd7dc2 Mon Sep 17 00:00:00 2001 From: Marian Beermann Date: Wed, 21 Jun 2017 00:16:25 +0200 Subject: [PATCH 3/3] docs: extract: move cwd note to --help --- docs/usage/extract.rst | 6 ------ src/borg/archiver.py | 5 +++++ 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/usage/extract.rst b/docs/usage/extract.rst index be9268962..292f84bdc 100644 --- a/docs/usage/extract.rst +++ b/docs/usage/extract.rst @@ -21,9 +21,3 @@ Examples # Restore a raw device (must not be active/in use/mounted at that time) $ borg extract --stdout /path/to/repo::my-sdx | dd of=/dev/sdx bs=10M - - -.. Note:: - - Currently, extract always writes into the current working directory ("."), - so make sure you ``cd`` to the right place before calling ``borg extract``. diff --git a/src/borg/archiver.py b/src/borg/archiver.py index e00e344a2..899c4c1d5 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -2893,6 +2893,11 @@ class Archiver: ``--progress`` can be slower than no progress display, since it makes one additional pass over the archive metadata. + + .. note:: + + Currently, extract always writes into the current working directory ("."), + so make sure you ``cd`` to the right place before calling ``borg extract``. """) subparser = subparsers.add_parser('extract', parents=[common_parser], add_help=False, description=self.do_extract.__doc__,