Merge pull request #2631 from enkore/docs/man-examples-fix

docs: fix build_man for relocated examples

docs/usage/create.rst

@@ -67,4 +67,4 @@ Examples
     # Backing up relative paths by moving into the correct directory first
     $ cd /home/user/Documents
     # The root directory of the archive will be "projectA"
-    $ borg create /path/to/repo::daily-projectA-{now:%Y-%m-%d} projectA
+    $ borg create /path/to/repo::daily-projectA-{now:%Y-%m-%d} projectA

docs/usage/extract.rst

@@ -26,4 +26,4 @@ Examples
 .. Note::
 
     Currently, extract always writes into the current working directory ("."),
-    so make sure you ``cd`` to the right place before calling ``borg extract``.
+    so make sure you ``cd`` to the right place before calling ``borg extract``.

docs/usage/init.rst

@@ -14,4 +14,4 @@ Examples
     $ borg init --encryption=repokey-blake2 user@hostname:backup
 
     # Remote repository (store the key your home dir)
-    $ borg init --encryption=keyfile user@hostname:backup
+    $ borg init --encryption=keyfile user@hostname:backup

setup.py

@@ -358,6 +358,23 @@ class build_man(Command):
 
     """)
 
+    usage_group = {
+        'break-lock': 'lock',
+        'with-lock': 'lock',
+
+        'change-passphrase': 'key',
+        'key_change-passphrase': 'key',
+        'key_export': 'key',
+        'key_import': 'key',
+        'key_migrate-to-repokey': 'key',
+
+        'export-tar': 'tar',
+
+        'benchmark_crud': 'benchmark',
+
+        'umount': 'mount',
+    }
+
     def initialize_options(self):
         pass
 
@@ -495,11 +512,15 @@ def write_man_header(self, write, title, description):
         write()
 
     def write_examples(self, write, command):
-        with open('docs/usage.rst') as fd:
+        command = command.replace(' ', '_')
+        with open('docs/usage/%s.rst' % self.usage_group.get(command, command)) as fd:
             usage = fd.read()
-            usage_include = '.. include:: usage/%s.rst.inc' % command
+            usage_include = '.. include:: %s.rst.inc' % command
             begin = usage.find(usage_include)
             end = usage.find('.. include', begin + 1)
+            # If a command has a dedicated anchor, it will occur before the command's include.
+            if 0 < usage.find('.. _', begin + 1) < end:
+                end = usage.find('.. _', begin + 1)
             examples = usage[begin:end]
             examples = examples.replace(usage_include, '')
             examples = examples.replace('Examples\n~~~~~~~~', '')