From 746ac11dbf6e4ad035fe55a20b1ead27916c236a Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Fri, 21 Jun 2019 10:43:33 +0100
Subject: [PATCH 1/2] Improve help and cmdline option names for
 --generate-config options

* group the arguments together into a group
* add new names "--generate-missing-config" and "--config-directory" for
  existing cmdline options "--generate-keys" and "--keys-dir", which better
  reflect their purposes.
---
 changelog.d/5512.feature |  1 +
 synapse/config/_base.py  | 50 ++++++++++++++++++++++------------------
 2 files changed, 29 insertions(+), 22 deletions(-)
 create mode 100644 changelog.d/5512.feature

diff --git a/changelog.d/5512.feature b/changelog.d/5512.feature
new file mode 100644
index 000000000000..712878901bf1
--- /dev/null
+++ b/changelog.d/5512.feature
@@ -0,0 +1 @@
+Improve help and cmdline option names for --generate-config options.
diff --git a/synapse/config/_base.py b/synapse/config/_base.py
index 8284aa4c6d36..2259d63fd0d4 100644
--- a/synapse/config/_base.py
+++ b/synapse/config/_base.py
@@ -241,37 +241,43 @@ def load_or_generate_config(cls, description, argv):
             help="Specify config file. Can be given multiple times and"
             " may specify directories containing *.yaml files.",
         )
-        config_parser.add_argument(
+
+        generate_group = config_parser.add_argument_group("Config generation")
+        generate_group.add_argument(
             "--generate-config",
             action="store_true",
-            help="Generate a config file for the server name",
+            help="Generate a config file, then exit.",
         )
-        config_parser.add_argument(
+        generate_group.add_argument(
+            "--generate-missing-configs",
+            "--generate-keys",
+            action="store_true",
+            help="Generate any missing additional config files, then exit.",
+        )
+        generate_group.add_argument(
+            "-H", "--server-name", help="The server name to generate a config file for."
+        )
+        generate_group.add_argument(
             "--report-stats",
             action="store",
-            help="Whether the generated config reports anonymized usage statistics",
+            help="Whether the generated config reports anonymized usage statistics.",
             choices=["yes", "no"],
         )
-        config_parser.add_argument(
-            "--generate-keys",
-            action="store_true",
-            help="Generate any missing key files then exit",
-        )
-        config_parser.add_argument(
+        generate_group.add_argument(
+            "--config-directory",
             "--keys-directory",
             metavar="DIRECTORY",
-            help="Used with 'generate-*' options to specify where files such as"
-            " signing keys should be stored, unless explicitly"
-            " specified in the config.",
-        )
-        config_parser.add_argument(
-            "-H", "--server-name", help="The server name to generate a config file for"
+            help=(
+                "Specify where additional config files such as signing keys and log"
+                " config should be stored. Defaults to the same directory as the main"
+                " config file."
+            ),
         )
         config_args, remaining_args = config_parser.parse_known_args(argv)
 
         config_files = find_config_files(search_paths=config_args.config_path)
 
-        generate_keys = config_args.generate_keys
+        generate_missing_configs = config_args.generate_missing_configs
 
         obj = cls()
 
@@ -289,8 +295,8 @@ def load_or_generate_config(cls, description, argv):
                 )
             (config_path,) = config_files
             if not cls.path_exists(config_path):
-                if config_args.keys_directory:
-                    config_dir_path = config_args.keys_directory
+                if config_args.config_directory:
+                    config_dir_path = config_args.config_directory
                 else:
                     config_dir_path = os.path.dirname(config_path)
                 config_dir_path = os.path.abspath(config_dir_path)
@@ -336,7 +342,7 @@ def load_or_generate_config(cls, description, argv):
                     )
                     % (config_path,)
                 )
-                generate_keys = True
+                generate_missing_configs = True
 
         parser = argparse.ArgumentParser(
             parents=[config_parser],
@@ -357,10 +363,10 @@ def load_or_generate_config(cls, description, argv):
         obj.read_config_files(
             config_files,
             keys_directory=config_args.keys_directory,
-            generate_keys=generate_keys,
+            generate_keys=generate_missing_configs,
         )
 
-        if generate_keys:
+        if generate_missing_configs:
             return None
 
         obj.invoke_all("read_arguments", args)

From 22d5eeb7a7cea334f65236dd09e72aedadbf3328 Mon Sep 17 00:00:00 2001
From: Richard van der Hoff <richard@matrix.org>
Date: Fri, 21 Jun 2019 17:55:30 +0100
Subject: [PATCH 2/2] fix tests

---
 synapse/config/_base.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/synapse/config/_base.py b/synapse/config/_base.py
index 2259d63fd0d4..0165e2aa68bc 100644
--- a/synapse/config/_base.py
+++ b/synapse/config/_base.py
@@ -362,7 +362,7 @@ def load_or_generate_config(cls, description, argv):
 
         obj.read_config_files(
             config_files,
-            keys_directory=config_args.keys_directory,
+            keys_directory=config_args.config_directory,
             generate_keys=generate_missing_configs,
         )