Merge pull request #2716 from enkore/docs/metavar

docs: format metavars more accurately

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``.

setup.py

@@ -203,6 +203,17 @@ def detect_libb2(prefixes):
     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 @@ def write_usage(self, parser, fp):
         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 @@ def gen_man_page(self, name, rst):
 
     def write_usage(self, write, parser):
         if any(len(o.option_strings) for o in parser._actions):
-            write(' <options> ', 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:

src/borg/archiver.py

@@ -2893,6 +2893,11 @@ def define_common_options(add_common_option):
 
         ``--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__,
@@ -3591,7 +3596,9 @@ def define_common_options(add_common_option):
         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
+        .. 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.
         """)