Merge pull request #2711 from enkore/docs/compact-opt

docs: change options formatting

docs/borg_theme/css/borg.css

@@ -109,7 +109,8 @@ table.docutils:not(.footnote) th {
     border: 1px solid #ddd;
 }
 
-table.docutils:not(.footnote) tr:first-child th {
+table.docutils:not(.footnote) tr:first-child th,
+table.docutils:not(.footnote) tr:first-child td {
     border-top: 0;
 }
 
@@ -118,15 +119,18 @@ table.docutils:not(.footnote) tr:last-child td {
 }
 
 table.docutils:not(.footnote) tr td:first-child,
-table.docutils:not(.footnote) tr th:first-child {
+table.docutils:not(.footnote) tr th:first-child,
+table.docutils.option-list tr td {
     border-left: 0;
 }
 
 table.docutils:not(.footnote) tr td:last-child,
-table.docutils:not(.footnote) tr th:last-child {
+table.docutils:not(.footnote) tr th:last-child,
+table.docutils.option-list tr td {
     border-right: 0;
 }
 
+kbd, /* used in usage pages for options */
 code,
 .rst-content tt.literal,
 .rst-content tt.literal,
@@ -141,6 +145,22 @@ p .literal span {
     background: none;
 }
 
+kbd {
+    box-shadow: none;
+    line-height: 23px;
+    word-wrap: normal;
+    font-size: 15px;
+    font-family: Consolas, monospace;
+}
+
+kbd .option {
+    white-space: nowrap;
+}
+
+table.docutils.option-list td.option-group {
+    min-width: 10em;
+}
+
 cite {
     white-space: nowrap;
     color: black; /* slight contrast with #404040 of regular text */
@@ -149,3 +169,7 @@ cite {
     font-style: normal;
     text-decoration: underline;
 }
+
+.borg-common-opt-ref {
+    font-weight: bold;
+}

docs/conf.py

@@ -105,8 +105,16 @@ html_theme_path = guzzle_sphinx_theme.html_theme_path()
 html_theme = 'guzzle_sphinx_theme'
 
 
+def set_rst_settings(app):
+    app.env.settings.update({
+        'field_name_limit': 0,
+        'option_limit': 0,
+    })
+
+
 def setup(app):
     app.add_stylesheet('css/borg.css')
+    app.connect('builder-inited', set_rst_settings)
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/usage/benchmark_crud.rst.inc

@@ -8,14 +8,16 @@ borg benchmark crud
 
     borg [common options] benchmark crud [options] REPO PATH
 
-positional arguments
-    REPO
-        repo to use for benchmark (must exist)
-    PATH
-        path were to create benchmark input data
+REPO
+    repo to use for benchmark (must exist)
+PATH
+    path were to create benchmark input data
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/break-lock.rst.inc

@@ -8,12 +8,14 @@ borg break-lock
 
     borg [common options] break-lock [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
-        repository for which to break the locks
+REPOSITORY
+    repository for which to break the locks
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/change-passphrase.rst.inc

@@ -8,12 +8,14 @@ borg change-passphrase
 
     borg [common options] change-passphrase [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
+REPOSITORY
 
 
+
+.. class:: borg-common-opt-ref
+
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/check.rst.inc

@@ -8,36 +8,30 @@ borg check
 
     borg [common options] check [options] REPOSITORY_OR_ARCHIVE
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        repository or archive to check consistency of
+REPOSITORY_OR_ARCHIVE
+    repository or archive to check consistency of
+
 
 optional arguments
-    ``--repository-only``
-        | only perform repository checks
-    ``--archives-only``
-        | only perform archives checks
-    ``--verify-data``
-        | perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
-    ``--repair``
-        | attempt to repair any inconsistencies found
-    ``--save-space``
-        | work slower, but using less space
+    --repository-only    only perform repository checks
+    --archives-only    only perform archives checks
+    --verify-data     perform cryptographic archive data integrity verification (conflicts with ``--repository-only``)
+    --repair          attempt to repair any inconsistencies found
+    --save-space      work slower, but using less space
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Description
 ~~~~~~~~~~~

docs/usage/common-options.rst.inc

@@ -1,36 +1,18 @@
-``-h``, ``--help``
-    | show this help message and exit
-``--critical``
-    | work on log level CRITICAL
-``--error``
-    | work on log level ERROR
-``--warning``
-    | work on log level WARNING (default)
-``--info``, ``-v``, ``--verbose``
-    | work on log level INFO
-``--debug``
-    | enable debug output, work on log level DEBUG
-``--debug-topic TOPIC``
-    | enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
-``-p``, ``--progress``
-    | show progress information
-``--log-json``
-    | Output one JSON object per log line instead of formatted text.
-``--lock-wait N``
-    | wait for the lock, but max. N seconds (default: 1).
-``--show-version``
-    | show/log the borg version
-``--show-rc``
-    | show/log the return code (rc)
-``--no-files-cache``
-    | do not load/update the file metadata cache used to detect unchanged files
-``--umask M``
-    | set umask to M (local and remote, default: 0077)
-``--remote-path PATH``
-    | use PATH as borg executable on the remote (default: "borg")
-``--remote-ratelimit rate``
-    | set remote network upload rate limit in kiByte/s (default: 0=unlimited)
-``--consider-part-files``
-    | treat part files like normal files (e.g. to list/extract them)
-``--debug-profile FILE``
-    | Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".
+-h, --help         show this help message and exit
+--critical         work on log level CRITICAL
+--error            work on log level ERROR
+--warning          work on log level WARNING (default)
+--info, -v, --verbose    work on log level INFO
+--debug            enable debug output, work on log level DEBUG
+--debug-topic TOPIC    enable TOPIC debugging (can be specified multiple times). The logger path is borg.debug.<TOPIC> if TOPIC is not fully qualified.
+-p, --progress     show progress information
+--log-json         Output one JSON object per log line instead of formatted text.
+--lock-wait N      wait for the lock, but max. N seconds (default: 1).
+--show-version     show/log the borg version
+--show-rc          show/log the return code (rc)
+--no-files-cache    do not load/update the file metadata cache used to detect unchanged files
+--umask M          set umask to M (local and remote, default: 0077)
+--remote-path PATH    use PATH as borg executable on the remote (default: "borg")
+--remote-ratelimit rate    set remote network upload rate limit in kiByte/s (default: 0=unlimited)
+--consider-part-files    treat part files like normal files (e.g. to list/extract them)
+--debug-profile FILE    Write execution profile in Borg format into FILE. For local use a Python-compatible file can be generated by suffixing FILE with ".pyprof".

docs/usage/create.rst.inc

@@ -8,70 +8,52 @@ borg create
 
     borg [common options] create [options] ARCHIVE PATH
 
-positional arguments
-    ARCHIVE
-        name of archive to create (must be also a valid directory name)
-    PATH
-        paths to archive
+ARCHIVE
+    name of archive to create (must be also a valid directory name)
+PATH
+    paths to archive
+
 
 optional arguments
-    ``-n``, ``--dry-run``
-        | do not create a backup archive
-    ``-s``, ``--stats``
-        | print statistics for the created archive
-    ``--list``
-        | output verbose list of items (files, dirs, ...)
-    ``--filter STATUSCHARS``
-        | only display items with the given status characters
-    ``--json``
-        | output stats as JSON (implies --stats)
-    ``--no-cache-sync``
-        | experimental: do not synchronize the cache. Implies --no-files-cache.
+    -n, --dry-run    do not create a backup archive
+    -s, --stats     print statistics for the created archive
+    --list          output verbose list of items (files, dirs, ...)
+    --filter STATUSCHARS    only display items with the given status characters
+    --json          output stats as JSON (implies --stats)
+    --no-cache-sync    experimental: do not synchronize the cache. Implies --no-files-cache.
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Exclusion options
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--exclude-caches``
-        | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
-    ``--exclude-if-present NAME``
-        | exclude directories that are tagged by containing a filesystem object with the given NAME
-    ``--keep-exclude-tags``, ``--keep-tag-files``
-        | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
+    -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+    --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+    --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
+    --keep-exclude-tags, --keep-tag-files    if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+
 
 Filesystem options
-    ``-x``, ``--one-file-system``
-        | stay in the same file system and do not store mount points of other file systems
-    ``--numeric-owner``
-        | only store numeric user and group identifiers
-    ``--noatime``
-        | do not store atime into archive
-    ``--noctime``
-        | do not store ctime into archive
-    ``--ignore-inode``
-        | ignore inode data in the file metadata cache used to detect unchanged files.
-    ``--read-special``
-        | open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
+    -x, --one-file-system     stay in the same file system and do not store mount points of other file systems
+    --numeric-owner           only store numeric user and group identifiers
+    --noatime                 do not store atime into archive
+    --noctime                 do not store ctime into archive
+    --ignore-inode            ignore inode data in the file metadata cache used to detect unchanged files.
+    --read-special            open and read block and char device files as well as FIFOs as if they were regular files. Also follows symlinks pointing to these kinds of files.
+
 
 Archive options
-    ``--comment COMMENT``
-        | add a comment text to the archive
-    ``--timestamp TIMESTAMP``
-        | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
-    ``-c SECONDS``, ``--checkpoint-interval SECONDS``
-        | write checkpoint every SECONDS seconds (Default: 1800)
-    ``--chunker-params PARAMS``
-        | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
-    ``-C COMPRESSION``, ``--compression COMPRESSION``
-        | select compression algorithm, see the output of the "borg help compression" command for details.
+    --comment COMMENT                             add a comment text to the archive
+    --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
+    -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
+    --chunker-params PARAMS                       specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE). default: 19,23,21,4095
+    -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
+
 
 Description
 ~~~~~~~~~~~

docs/usage/delete.rst.inc

@@ -8,34 +8,29 @@ borg delete
 
     borg [common options] delete [options] TARGET
 
-positional arguments
-    TARGET
-        archive or repository to delete
+TARGET
+    archive or repository to delete
+
 
 optional arguments
-    ``-s``, ``--stats``
-        | print statistics for the deleted archive
-    ``-c``, ``--cache-only``
-        | delete only the local cache for the given repository
-    ``--force``
-        | force deletion of corrupted archives, use --force --force in case --force does not work.
-    ``--save-space``
-        | work slower, but using less space
+    -s, --stats     print statistics for the deleted archive
+    -c, --cache-only    delete only the local cache for the given repository
+    --force         force deletion of corrupted archives, use --force --force in case --force does not work.
+    --save-space    work slower, but using less space
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Description
 ~~~~~~~~~~~

docs/usage/diff.rst.inc

@@ -8,40 +8,34 @@ borg diff
 
     borg [common options] diff [options] REPO_ARCHIVE1 ARCHIVE2 PATH
 
-positional arguments
-    REPO_ARCHIVE1
-        repository location and ARCHIVE1 name
-    ARCHIVE2
-        ARCHIVE2 name (no repository location allowed)
-    PATH
-        paths of items inside the archives to compare; patterns are supported
+REPO_ARCHIVE1
+    repository location and ARCHIVE1 name
+ARCHIVE2
+    ARCHIVE2 name (no repository location allowed)
+PATH
+    paths of items inside the archives to compare; patterns are supported
+
 
 optional arguments
-    ``--numeric-owner``
-        | only consider numeric user and group identifiers
-    ``--same-chunker-params``
-        | Override check of chunker parameters.
-    ``--sort``
-        | Sort the output lines by file path.
+    --numeric-owner    only consider numeric user and group identifiers
+    --same-chunker-params    Override check of chunker parameters.
+    --sort     Sort the output lines by file path.
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Exclusion options
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--exclude-caches``
-        | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
-    ``--exclude-if-present NAME``
-        | exclude directories that are tagged by containing a filesystem object with the given NAME
-    ``--keep-exclude-tags``, ``--keep-tag-files``
-        | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
+    -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+    --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+    --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
+    --keep-exclude-tags, --keep-tag-files    if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+
 
 Description
 ~~~~~~~~~~~

docs/usage/export-tar.rst.inc

@@ -8,32 +8,28 @@ borg export-tar
 
     borg [common options] export-tar [options] ARCHIVE FILE PATH
 
-positional arguments
-    ARCHIVE
-        archive to export
-    FILE
-        output tar file. "-" to write to stdout instead.
-    PATH
-        paths to extract; patterns are supported
+ARCHIVE
+    archive to export
+FILE
+    output tar file. "-" to write to stdout instead.
+PATH
+    paths to extract; patterns are supported
+
 
 optional arguments
-    ``--tar-filter``
-        | filter program to pipe data through
-    ``--list``
-        | output verbose list of items (files, dirs, ...)
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
-    ``--strip-components NUMBER``
-        | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+    --tar-filter                      filter program to pipe data through
+    --list                            output verbose list of items (files, dirs, ...)
+    -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+    --strip-components NUMBER         Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/extract.rst.inc

@@ -8,36 +8,29 @@ borg extract
 
     borg [common options] extract [options] ARCHIVE PATH
 
-positional arguments
-    ARCHIVE
-        archive to extract
-    PATH
-        paths to extract; patterns are supported
+ARCHIVE
+    archive to extract
+PATH
+    paths to extract; patterns are supported
+
 
 optional arguments
-    ``--list``
-        | output verbose list of items (files, dirs, ...)
-    ``-n``, ``--dry-run``
-        | do not actually change any files
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
-    ``--numeric-owner``
-        | only obey numeric user and group identifiers
-    ``--strip-components NUMBER``
-        | Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
-    ``--stdout``
-        | write all extracted data to stdout
-    ``--sparse``
-        | create holes in output sparse file from all-zero chunks
+    --list            output verbose list of items (files, dirs, ...)
+    -n, --dry-run     do not actually change any files
+    -e PATTERN, --exclude PATTERN    exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE    read exclude patterns from EXCLUDEFILE, one per line
+    --pattern PATTERN    experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE    experimental: read include/exclude patterns from PATTERNFILE, one per line
+    --numeric-owner    only obey numeric user and group identifiers
+    --strip-components NUMBER    Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped.
+    --stdout          write all extracted data to stdout
+    --sparse          create holes in output sparse file from all-zero chunks
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/info.rst.inc

@@ -8,28 +8,26 @@ borg info
 
     borg [common options] info [options] REPOSITORY_OR_ARCHIVE
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        archive or repository to display information about
+REPOSITORY_OR_ARCHIVE
+    archive or repository to display information about
+
 
 optional arguments
-    ``--json``
-        | format output as JSON
+    --json     format output as JSON
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Description
 ~~~~~~~~~~~

docs/usage/init.rst.inc

@@ -8,20 +8,20 @@ borg init
 
     borg [common options] init [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
-        repository to create
+REPOSITORY
+    repository to create
+
 
 optional arguments
-    ``-e``, ``--encryption``
-        | select encryption key mode **(required)**
-    ``--append-only``
-        | create an append-only mode repository
-    ``--storage-quota``
-        | Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+    -e, --encryption     select encryption key mode **(required)**
+    --append-only        create an append-only mode repository
+    --storage-quota      Set storage quota of the new repository (e.g. 5G, 1.5T). Default: no quota.
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/key.rst

@@ -1,8 +1,3 @@
-.. include:: key_export.rst.inc
-
-
-.. include:: key_import.rst.inc
-
 .. _borg-change-passphrase:
 
 .. include:: key_change-passphrase.rst.inc
@@ -40,3 +35,7 @@ Fully automated using environment variables:
     $ BORG_PASSPHRASE=old BORG_NEW_PASSPHRASE=new borg key change-passphrase repo
     # now "new" is the current passphrase.
 
+
+.. include:: key_export.rst.inc
+
+.. include:: key_import.rst.inc

docs/usage/key_change-passphrase.rst.inc

@@ -8,12 +8,14 @@ borg key change-passphrase
 
     borg [common options] key change-passphrase [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
+REPOSITORY
 
 
+
+.. class:: borg-common-opt-ref
+
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/key_export.rst.inc

@@ -8,20 +8,21 @@ borg key export
 
     borg [common options] key export [options] REPOSITORY PATH
 
-positional arguments
-    REPOSITORY
+REPOSITORY
+
+PATH
+    where to store the backup
 
-    PATH
-        where to store the backup
 
 optional arguments
-    ``--paper``
-        | Create an export suitable for printing and later type-in
-    ``--qr-html``
-        | Create an html file suitable for printing and later type-in or qr scan
+    --paper       Create an export suitable for printing and later type-in
+    --qr-html     Create an html file suitable for printing and later type-in or qr scan
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/key_import.rst.inc

@@ -8,18 +8,20 @@ borg key import
 
     borg [common options] key import [options] REPOSITORY PATH
 
-positional arguments
-    REPOSITORY
+REPOSITORY
+
+PATH
+    path to the backup
 
-    PATH
-        path to the backup
 
 optional arguments
-    ``--paper``
-        | interactively import from a backup done with ``--paper``
+    --paper     interactively import from a backup done with ``--paper``
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/key_migrate-to-repokey.rst.inc

@@ -8,12 +8,14 @@ borg key migrate-to-repokey
 
     borg [common options] key migrate-to-repokey [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
+REPOSITORY
 
 
+
+.. class:: borg-common-opt-ref
+
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/list.rst.inc

@@ -8,53 +8,42 @@ borg list
 
     borg [common options] list [options] REPOSITORY_OR_ARCHIVE PATH
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        repository/archive to list contents of
-    PATH
-        paths to list; patterns are supported
+REPOSITORY_OR_ARCHIVE
+    repository/archive to list contents of
+PATH
+    paths to list; patterns are supported
+
 
 optional arguments
-    ``--short``
-        | only print file/directory names, nothing else
-    ``--format``, ``--list-format``
-        | specify format for file listing
-        |                                 (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
-    ``--json``
-        | Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
-    ``--json-lines``
-        | Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
+    --short     only print file/directory names, nothing else
+    --format, --list-format    specify format for file listing
+                                    (default: "{mode} {user:6} {group:6} {size:8d} {isomtime} {path}{extra}{NL}")
+    --json      Only valid for listing repository contents. Format output as JSON. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "barchive" key is therefore not available.
+    --json-lines    Only valid for listing archive contents. Format output as JSON Lines. The form of ``--format`` is ignored, but keys used in it are added to the JSON output. Some keys are always present. Note: JSON can only represent text. A "bpath" key is therefore not available.
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Exclusion options
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--exclude-caches``
-        | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
-    ``--exclude-if-present NAME``
-        | exclude directories that are tagged by containing a filesystem object with the given NAME
-    ``--keep-exclude-tags``, ``--keep-tag-files``
-        | if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
+    -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+    --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+    --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
+    --keep-exclude-tags, --keep-tag-files    if tag objects are specified with --exclude-if-present, don't omit the tag objects themselves from the backup archive
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+
 
 Description
 ~~~~~~~~~~~

docs/usage/mount.rst.inc

@@ -8,32 +8,29 @@ borg mount
 
     borg [common options] mount [options] REPOSITORY_OR_ARCHIVE MOUNTPOINT
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        repository/archive to mount
-    MOUNTPOINT
-        where to mount filesystem
+REPOSITORY_OR_ARCHIVE
+    repository/archive to mount
+MOUNTPOINT
+    where to mount filesystem
+
 
 optional arguments
-    ``-f``, ``--foreground``
-        | stay in foreground, do not daemonize
-    ``-o``
-        | Extra mount options
+    -f, --foreground    stay in foreground, do not daemonize
+    -o     Extra mount options
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
-    ``--sort-by``
-        | Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
-    ``--first N``
-        | consider first N archives after other filters were applied
-    ``--last N``
-        | consider last N archives after other filters were applied
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    --sort-by               Comma-separated list of sorting keys; valid keys are: timestamp, name, id; default is: timestamp
+    --first N               consider first N archives after other filters were applied
+    --last N                consider last N archives after other filters were applied
+
 
 Description
 ~~~~~~~~~~~

docs/usage/prune.rst.inc

@@ -8,46 +8,35 @@ borg prune
 
     borg [common options] prune [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
-        repository to prune
+REPOSITORY
+    repository to prune
+
 
 optional arguments
-    ``-n``, ``--dry-run``
-        | do not change repository
-    ``--force``
-        | force pruning of corrupted archives
-    ``-s``, ``--stats``
-        | print statistics for the deleted archive
-    ``--list``
-        | output verbose list of archives it keeps/prunes
-    ``--keep-within WITHIN``
-        | keep all archives within this time interval
-    ``--keep-last``, ``--keep-secondly``
-        | number of secondly archives to keep
-    ``--keep-minutely``
-        | number of minutely archives to keep
-    ``-H``, ``--keep-hourly``
-        | number of hourly archives to keep
-    ``-d``, ``--keep-daily``
-        | number of daily archives to keep
-    ``-w``, ``--keep-weekly``
-        | number of weekly archives to keep
-    ``-m``, ``--keep-monthly``
-        | number of monthly archives to keep
-    ``-y``, ``--keep-yearly``
-        | number of yearly archives to keep
-    ``--save-space``
-        | work slower, but using less space
+    -n, --dry-run         do not change repository
+    --force               force pruning of corrupted archives
+    -s, --stats           print statistics for the deleted archive
+    --list                output verbose list of archives it keeps/prunes
+    --keep-within WITHIN    keep all archives within this time interval
+    --keep-last, --keep-secondly    number of secondly archives to keep
+    --keep-minutely       number of minutely archives to keep
+    -H, --keep-hourly     number of hourly archives to keep
+    -d, --keep-daily      number of daily archives to keep
+    -w, --keep-weekly     number of weekly archives to keep
+    -m, --keep-monthly    number of monthly archives to keep
+    -y, --keep-yearly     number of yearly archives to keep
+    --save-space          work slower, but using less space
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 filters
-    ``-P``, ``--prefix``
-        | only consider archive names starting with this prefix.
-    ``-a``, ``--glob-archives``
-        | only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+    -P, --prefix            only consider archive names starting with this prefix.
+    -a, --glob-archives     only consider archive names matching the glob. sh: rules apply, see "borg help patterns". ``--prefix`` and ``--glob-archives`` are mutually exclusive.
+
 
 Description
 ~~~~~~~~~~~

docs/usage/recreate.rst.inc

@@ -8,56 +8,43 @@ borg recreate
 
     borg [common options] recreate [options] REPOSITORY_OR_ARCHIVE PATH
 
-positional arguments
-    REPOSITORY_OR_ARCHIVE
-        repository/archive to recreate
-    PATH
-        paths to recreate; patterns are supported
+REPOSITORY_OR_ARCHIVE
+    repository/archive to recreate
+PATH
+    paths to recreate; patterns are supported
+
 
 optional arguments
-    ``--list``
-        | output verbose list of items (files, dirs, ...)
-    ``--filter STATUSCHARS``
-        | only display items with the given status characters
-    ``-n``, ``--dry-run``
-        | do not change anything
-    ``-s``, ``--stats``
-        | print statistics at end
+    --list          output verbose list of items (files, dirs, ...)
+    --filter STATUSCHARS    only display items with the given status characters
+    -n, --dry-run    do not change anything
+    -s, --stats     print statistics at end
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Exclusion options
-    ``-e PATTERN``, ``--exclude PATTERN``
-        | exclude paths matching PATTERN
-    ``--exclude-from EXCLUDEFILE``
-        | read exclude patterns from EXCLUDEFILE, one per line
-    ``--exclude-caches``
-        | exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
-    ``--exclude-if-present NAME``
-        | exclude directories that are tagged by containing a filesystem object with the given NAME
-    ``--keep-exclude-tags``, ``--keep-tag-files``
-        | if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
-    ``--pattern PATTERN``
-        | experimental: include/exclude paths matching PATTERN
-    ``--patterns-from PATTERNFILE``
-        | experimental: read include/exclude patterns from PATTERNFILE, one per line
+    -e PATTERN, --exclude PATTERN     exclude paths matching PATTERN
+    --exclude-from EXCLUDEFILE        read exclude patterns from EXCLUDEFILE, one per line
+    --exclude-caches                  exclude directories that contain a CACHEDIR.TAG file (http://www.brynosaurus.com/cachedir/spec.html)
+    --exclude-if-present NAME         exclude directories that are tagged by containing a filesystem object with the given NAME
+    --keep-exclude-tags, --keep-tag-files    if tag objects are specified with ``--exclude-if-present``, don't omit the tag objects themselves from the backup archive
+    --pattern PATTERN                 experimental: include/exclude paths matching PATTERN
+    --patterns-from PATTERNFILE       experimental: read include/exclude patterns from PATTERNFILE, one per line
+
 
 Archive options
-    ``--target TARGET``
-        | create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
-    ``-c SECONDS``, ``--checkpoint-interval SECONDS``
-        | write checkpoint every SECONDS seconds (Default: 1800)
-    ``--comment COMMENT``
-        | add a comment text to the archive
-    ``--timestamp TIMESTAMP``
-        | manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
-    ``-C COMPRESSION``, ``--compression COMPRESSION``
-        | select compression algorithm, see the output of the "borg help compression" command for details.
-    ``--recompress``
-        | recompress data chunks according to ``--compression`` if `if-different`. When `always`, chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for `if-different`, not the compression level (if any).
-    ``--chunker-params PARAMS``
-        | specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: 19,23,21,4095
+    --target TARGET                               create a new archive with the name ARCHIVE, do not replace existing archive (only applies for a single archive)
+    -c SECONDS, --checkpoint-interval SECONDS     write checkpoint every SECONDS seconds (Default: 1800)
+    --comment COMMENT                             add a comment text to the archive
+    --timestamp TIMESTAMP                         manually specify the archive creation date/time (UTC, yyyy-mm-ddThh:mm:ss format). alternatively, give a reference file/directory.
+    -C COMPRESSION, --compression COMPRESSION     select compression algorithm, see the output of the "borg help compression" command for details.
+    --recompress                                  recompress data chunks according to ``--compression`` if `if-different`. When `always`, chunks that are already compressed that way are not skipped, but compressed again. Only the algorithm is considered for `if-different`, not the compression level (if any).
+    --chunker-params PARAMS                       specify the chunker parameters (CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS, HASH_WINDOW_SIZE) or `default` to use the current defaults. default: 19,23,21,4095
+
 
 Description
 ~~~~~~~~~~~

docs/usage/rename.rst.inc

@@ -8,14 +8,16 @@ borg rename
 
     borg [common options] rename [options] ARCHIVE NEWNAME
 
-positional arguments
-    ARCHIVE
-        archive to rename
-    NEWNAME
-        the new archive name to use
+ARCHIVE
+    archive to rename
+NEWNAME
+    the new archive name to use
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/serve.rst.inc

@@ -8,18 +8,19 @@ borg serve
 
     borg [common options] serve [options]
 
+
+
 optional arguments
-    ``--restrict-to-path PATH``
-        | restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
-    ``--restrict-to-repository PATH``
-        | restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike --restrict-to-path sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
-    ``--append-only``
-        | only allow appending to repository segment files
-    ``--storage-quota``
-        | Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
+    --restrict-to-path PATH    restrict repository access to PATH. Can be specified multiple times to allow the client access to several directories. Access to all sub-directories is granted implicitly; PATH doesn't need to directly point to a repository.
+    --restrict-to-repository PATH    restrict repository access. Only the repository located at PATH (no sub-directories are considered) is accessible. Can be specified multiple times to allow the client access to several repositories. Unlike --restrict-to-path sub-directories are not accessible; PATH needs to directly point at a repository location. PATH may be an empty directory or the last element of PATH may not exist, in which case the client may initialize a repository there.
+    --append-only       only allow appending to repository segment files
+    --storage-quota     Override storage quota of the repository (e.g. 5G, 1.5T). When a new repository is initialized, sets the storage quota on the new repository as well. Default: no quota.
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/umount.rst.inc

@@ -8,12 +8,14 @@ borg umount
 
     borg [common options] umount [options] MOUNTPOINT
 
-positional arguments
-    MOUNTPOINT
-        mountpoint of the filesystem to umount
+MOUNTPOINT
+    mountpoint of the filesystem to umount
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/upgrade.rst.inc

@@ -8,25 +8,23 @@ borg upgrade
 
     borg [common options] upgrade [options] REPOSITORY
 
-positional arguments
-    REPOSITORY
-        path to the repository to be upgraded
+REPOSITORY
+    path to the repository to be upgraded
+
 
 optional arguments
-    ``-n``, ``--dry-run``
-        | do not change repository
-    ``--inplace``
-        | rewrite repository in place, with no chance of going back to older
-        |                                versions of the repository.
-    ``--force``
-        | Force upgrade
-    ``--tam``
-        | Enable manifest authentication (in key and cache) (Borg 1.0.9 and later)
-    ``--disable-tam``
-        | Disable manifest authentication (in key and cache)
+    -n, --dry-run     do not change repository
+    --inplace         rewrite repository in place, with no chance of going back to older
+                                   versions of the repository.
+    --force           Force upgrade
+    --tam             Enable manifest authentication (in key and cache) (Borg 1.0.9 and later)
+    --disable-tam     Disable manifest authentication (in key and cache)
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

docs/usage/with-lock.rst.inc

@@ -8,16 +8,18 @@ borg with-lock
 
     borg [common options] with-lock [options] REPOSITORY COMMAND ARGS
 
-positional arguments
-    REPOSITORY
-        repository to lock
-    COMMAND
-        command to run
-    ARGS
-        command arguments
+REPOSITORY
+    repository to lock
+COMMAND
+    command to run
+ARGS
+    command arguments
+
+
+.. class:: borg-common-opt-ref
 
 :ref:`common_options`
-    |
+
 
 Description
 ~~~~~~~~~~~

setup.py

@@ -285,12 +285,12 @@ class build_usage(Command):
             if option.option_strings:
                 continue
             fp.write(' ' + option.metavar)
+        fp.write('\n\n')
 
     def write_options(self, parser, fp):
         for group in parser._action_groups:
             if group.title == 'Common options':
-                fp.write('\n\n:ref:`common_options`\n')
-                fp.write('    |')
+                fp.write('\n\n.. class:: borg-common-opt-ref\n\n:ref:`common_options`\n')
             else:
                 self.write_options_group(group, fp)
 
@@ -298,12 +298,13 @@ class build_usage(Command):
         def is_positional_group(group):
             return any(not o.option_strings for o in group._group_actions)
 
-        def get_help(option):
-            text = textwrap.dedent((option.help or '') % option.__dict__)
-            return '\n'.join('| ' + line for line in text.splitlines())
+        indent = ' ' * base_indent
 
-        def shipout(text):
-            fp.write(textwrap.indent('\n'.join(text), ' ' * base_indent))
+        if is_positional_group(group):
+            for option in group._group_actions:
+                fp.write(option.metavar + '\n')
+                fp.write(textwrap.indent(option.help or '', ' ' * base_indent) + '\n')
+            return
 
         if not group._group_actions:
             return
@@ -311,28 +312,22 @@ class build_usage(Command):
         if with_title:
             fp.write('\n\n')
             fp.write(group.title + '\n')
-        text = []
 
-        if is_positional_group(group):
-            for option in group._group_actions:
-                text.append(option.metavar)
-                text.append(textwrap.indent(option.help or '', ' ' * 4))
-            shipout(text)
-            return
+        opts = OrderedDict()
 
-        options = []
         for option in group._group_actions:
             if option.metavar:
-                option_fmt = '``%%s %s``' % option.metavar
+                option_fmt = '%s ' + option.metavar
             else:
-                option_fmt = '``%s``'
+                option_fmt = '%s'
             option_str = ', '.join(option_fmt % s for s in option.option_strings)
-            options.append((option_str, option))
-        for option_str, option in options:
-            help = textwrap.indent(get_help(option), ' ' * 4)
-            text.append(option_str)
-            text.append(help)
-        shipout(text)
+            option_desc = textwrap.dedent((option.help or '') % option.__dict__)
+            opts[option_str] = textwrap.indent(option_desc, ' ' * 4)
+
+        padding = len(max(opts)) + 1
+
+        for option, desc in opts.items():
+            fp.write(indent + option.ljust(padding) + desc + '\n')
 
 
 class build_man(Command):