Implement our fancy new --help output

certbot/cli.py

@@ -81,6 +81,7 @@
 manage certificates:
     certificates    Display information about certs you have from Certbot
     revoke          Revoke a certificate (supply --cert-path)
+    rename          Rename a certificate
 
 manage your account with Let's Encrypt:
     register        Create a Let's Encrypt ACME account
@@ -340,7 +341,7 @@ def add_argument(self, *args, **kwargs):
         "short": "Revoke a certificate specified with --cert-path",
         "opts": "Options for revocation of certs"
     }),
-    ("revoke", {
+    ("rename", {
         "short": "Change a certificate's name (for management purposes)",
         "opts": "Options changing certificate names"
     }),
@@ -366,7 +367,7 @@ def add_argument(self, *args, **kwargs):
     }),
     ("update_symlinks", {
         "short": "Recreate symlinks in your /live/ directory",
-        "opts": ("Recreates cert and key symlinks in {0}, if you changed them by hand, "
+        "opts": ("Recreates cert and key symlinks in {0}, if you changed them by hand "
                  "or edited a renewal configuration file".format(
                   os.path.join(flag_default("config_dir"), "live")))
     }),
@@ -398,7 +399,7 @@ def __init__(self, args, plugins, detect_defaults=False):
 
         # List of topics for which additional help can be provided
         HELP_TOPICS = ["all", "security", "paths", "automation", "testing"] + list(self.VERBS)
-        HELP_TOPICS += self.COMMANDS_TOPICS
+        HELP_TOPICS += self.COMMANDS_TOPICS + ["manage"]
 
         plugin_names = list(plugins)
         self.help_topics = HELP_TOPICS + plugin_names + [None]
@@ -437,10 +438,9 @@ def _list_subcommands(self):
         longest = max(len(v) for v in VERB_HELP_MAP.keys())
 
         text = "The full list of available SUBCOMMANDS is:\n\n"
-        for verb, props in VERB_HELP:
-            padding = (longest - len(verb)) + 4
+        for verb, props in sorted(VERB_HELP):
             doc = props.get("short", "")
-            text += verb + " " * padding + doc + "\n"
+            text += '{0:<{length}}     {1}\n'.format(verb, doc, length=longest)
 
         text += "\nYou can get more help on a specific subcommand with --help SUBCOMMAND\n"
         return text
@@ -683,21 +683,26 @@ def add_deprecated_argument(self, argument_name, num_args):
         util.add_deprecated_argument(
             self.parser.add_argument, argument_name, num_args)
 
-    def add_group(self, topic, **kwargs):
+    def add_group(self, topic, verbs=(), **kwargs):
         """Create a new argument group.
 
         This method must be called once for every topic, however, calls
         to this function are left next to the argument definitions for
         clarity.
 
         :param str topic: Name of the new argument group.
+        :param str verbs: List of subcommands that should be documented as part of
+                          this help group / topic
 
         :returns: The new argument group.
         :rtype: `HelpfulArgumentGroup`
 
         """
         if self.visible_topics[topic]:
             self.groups[topic] = self.parser.add_argument_group(topic, **kwargs)
+            if self.help_arg:
+                for v in verbs:
+                    self.groups[topic].add_argument(v, help=VERB_HELP_MAP[v]["short"])
 
         return HelpfulArgumentGroup(self, topic)
 
@@ -738,10 +743,12 @@ def determine_help_topics(self, chosen_topic):
 def _add_all_groups(helpful):
     helpful.add_group("automation", description="Arguments for automating execution & other tweaks")
     helpful.add_group("security", description="Security parameters & server settings")
-    helpful.add_group(
-        "testing", description="The following flags are meant for "
-        "testing and integration purposes only.")
+    helpful.add_group("testing",
+        description="The following flags are meant for testing and integration purposes only.")
     helpful.add_group("paths", description="Arguments changing execution paths & servers")
+    helpful.add_group("manage",
+        description="Various subcommands and flags are available for managing your certificates:",
+        verbs=["certificates", "renew", "revoke", "rename"])
 
     # VERBS
     for verb, docs in VERB_HELP:
@@ -788,15 +795,15 @@ def prepare_and_parse_args(plugins, args, detect_defaults=False):  # pylint: dis
              "multiple -d flags or enter a comma separated list of domains "
              "as a parameter.")
     helpful.add(
-        [None, "run", "certonly"],
+        [None, "run", "certonly", "manage"],
         "--cert-name", dest="certname",
         metavar="CERTNAME", default=None,
         help="Certificate name to apply. Only one certificate name can be used "
              "per Certbot run. To see certificate names, run 'certbot certificates'."
              "If there is no existing certificate with this name and "
              "domains are requested, create a new certificate with this name.")
     helpful.add(
-        "rename",
+        ["rename", "manage"],
         "--updated-cert-name", dest="new_certname",
         metavar="NEW_CERTNAME", default=None,
         help="New name for the certificate. Must be a valid filename.")
@@ -1051,9 +1058,7 @@ def _paths_parser(helpful):
         verb = helpful.help_arg
 
     cph = "Path to where cert is saved (with auth --csr), installed from or revoked."
-    section = "paths"
-    if verb in ("install", "revoke", "certonly"):
-        section = verb
+    section = ["paths", "install", "revoke", "certonly", "manage"]
     if verb == "certonly":
         add(section, "--cert-path", type=os.path.abspath,
             default=flag_default("auth_cert_path"), help=cph)

docs/cli-help.txt

@@ -24,6 +24,7 @@ obtain, install, and renew certificates:
 manage certificates:
     certificates    Display information about certs you have from Certbot
     revoke          Revoke a certificate (supply --cert-path)
+    rename          Rename a certificate
 
 manage your account with Let's Encrypt:
     register        Create a Let's Encrypt ACME account
@@ -53,9 +54,6 @@ optional arguments:
                         certificate with this name and domains are requested,
                         create a new certificate with this name. (default:
                         None)
-  --updated-cert-name NEW_CERTNAME
-                        New name for the certificate. Must be a valid
-                        filename. (default: None)
   --dry-run             Perform a test run of the client, obtaining test
                         (invalid) certs but not saving them to disk. This can
                         currently only be used with the 'certonly' and 'renew'
@@ -210,6 +208,16 @@ paths:
   --server SERVER       ACME Directory Resource URI. (default:
                         https://acme-v01.api.letsencrypt.org/directory)
 
+manage:
+  Various subcommands and flags are available for managing your
+  certificates:
+
+  certificates          List all certificates managed by Certbot
+  renew                 Renew all certificates (or one specifed with --cert-
+                        name)
+  revoke                Revoke a certificate specified with --cert-path
+  rename                Change a certificate's name (for management purposes)
+
 run:
   Options for obtaining & installing certs
 
@@ -268,9 +276,13 @@ certificates:
 revoke:
   Options for revocation of certs
 
-revoke:
+rename:
   Options changing certificate names
 
+  --updated-cert-name NEW_CERTNAME
+                        New name for the certificate. Must be a valid
+                        filename. (default: None)
+
 register:
   Options for account registration & modification
 
@@ -322,7 +334,7 @@ plugins:
 
 update_symlinks:
   Recreates cert and key symlinks in /etc/letsencrypt/live, if you changed
-  them by hand, or edited a renewal configuration file
+  them by hand or edited a renewal configuration file
 
 plugins:
   Plugin Selection: Certbot client supports an extensible plugins