improve LINSTOR client command help text

linstor_client/commands/backup_cmds.py

@@ -106,7 +106,7 @@ def setup_commands(self, parser):
         p_lbackups.add_argument(
             '-o', '--others',
             action="store_true",
-            help='Only show s3 objects that are unknown to Linstor')
+            help='Only show S3 objects that are unknown to LINSTOR')
         p_lbackups.add_argument(
             '-i', '--show-id',
             action="store_true",
@@ -145,7 +145,7 @@ def setup_commands(self, parser):
             Commands.Subcommands.Delete.LONG,
             aliases=[Commands.Subcommands.Delete.SHORT],
             formatter_class=argparse.RawTextHelpFormatter,
-            description="Delete backup(s) from a remote")
+            description="Delete backup(s) from a remote.")
         p_delbak_subp = p_delbak.add_subparsers(
             title="Delete backup commands",
             metavar="",
@@ -188,18 +188,18 @@ def setup_commands(self, parser):
         p_delbak_all = p_delbak_subp.add_parser(
             BackupCommands.DeleteAll.LONG,
             aliases=[BackupCommands.DeleteAll.SHORT],
-            description="Delete all Linstor backups of the given remote. Will NOT delete non-Linstor S3 objects")
+            description="Delete all LINSTOR backups of the given remote. Will NOT delete non-LINSTOR S3 objects")
         self._add_remote(p_delbak_all)
         p_delbak_all.add_argument(
             "-c", "--cluster",
             action="store_true",
-            help="Only delete Linstor backups created by the local cluster")
+            help="Only delete LINSTOR backups created by the local cluster")
         p_delbak_all.set_defaults(func=self.del_all)
 
         p_delbak_s3 = p_delbak_subp.add_parser(
             BackupCommands.DeleteS3Key.LONG,
             aliases=[BackupCommands.DeleteS3Key.SHORT],
-            description="Delete a given S3 object. Use this option to delete non-Linstor S3 objects")
+            description="Delete a given S3 object. Use this option to delete non-LINSTOR S3 objects")
         self._add_remote(p_delbak_s3)
         p_delbak_s3.add_argument(
             "s3key",
@@ -264,7 +264,7 @@ def setup_commands(self, parser):
             Commands.Subcommands.Abort.LONG,
             aliases=[Commands.Subcommands.Abort.SHORT],
             description="Aborts a backup. If neither --create nor --restore is given, both will be aborted (if any in "
-                        "progress)")
+                        "progress).")
         self._add_remote(p_crtabort)
         p_crtabort.add_argument(
             "resource",
@@ -298,7 +298,7 @@ def setup_commands(self, parser):
         p_lstqueue = p_queuebak_subp.add_parser(
             Commands.Subcommands.List.LONG,
             aliases=[Commands.Subcommands.List.SHORT],
-            description="Lists all queued backups by listing each node and all backups queued on it.")
+            description="Lists backups that are queued on nodes.")
         p_lstqueue.add_argument('-p', '--pastable', action="store_true", help='Generate pastable output')
         p_lstqueue.add_argument(
             "-n", "--nodes",
@@ -330,23 +330,23 @@ def setup_commands(self, parser):
         p_shipbak = bkp_sub.add_parser(
             BackupCommands.Ship.LONG,
             aliases=[BackupCommands.Ship.SHORT],
-            description="Ships a backup to another Linstor cluster")
+            description="Ships a backup to another LINSTOR cluster.")
         self._add_remote(p_shipbak)
         p_shipbak.add_argument(
             "source_resource",
             help="The local resource name to ship")
         p_shipbak.add_argument(
             "target_resource",
-            help="The resource name on the target Linstor cluster")
+            help="The resource name on the target LINSTOR cluster")
         p_shipbak.add_argument(
             "--source-node",
             help="Prefer the given node to send the backup")
         p_shipbak.add_argument(
             "--target-node",
-            help="Specify which node in the target Linstor cluster should receive the backup")
+            help="Specify which node in the target LINSTOR cluster should receive the backup")
         p_shipbak.add_argument(
             "--target-net-if",
-            help="Specify on which Linstor network interface the target node should listen")
+            help="Specify on which LINSTOR network interface the target node should listen")
         p_shipbak.add_argument(
             "--target-storage-pool",
             help="Specify in which target storage pool the backup should be received")
@@ -373,7 +373,7 @@ def setup_commands(self, parser):
             BackupCommands.Info.LONG,
             aliases=[BackupCommands.Info.SHORT],
             description="Retrieve information about a given backup. Either --id OR --resource must be used (not both)."
-                        " Option --storpool-rename must be used in combination with --target-node")
+                        " Option --storpool-rename must be used in combination with --target-node.")
         self._add_remote(p_infobak)
         p_infobak.add_argument(
             "-r", "--resource",
@@ -407,7 +407,7 @@ def setup_commands(self, parser):
             Commands.Subcommands.Schedule.LONG,
             aliases=[Commands.Subcommands.Schedule.SHORT],
             formatter_class=argparse.RawTextHelpFormatter,
-            description="Schedule backup(s) from a remote")
+            description="Schedule backup(s) from a remote.")
         p_schedbak_subp = p_schedbak.add_subparsers(
             title="Schedule backup commands",
             metavar="",

linstor_client/commands/commands.py

@@ -1132,29 +1132,31 @@ def setup_commands(self, parser):
         c_sos_create = sos_subp.add_parser(
             Commands.Subcommands.Create.LONG,
             aliases=[Commands.Subcommands.Create.SHORT],
-            description='Create a sos report on the controller'
+            description='Create an SOS report on the controller (by default in the `/var/log/linstor-controller` '
+            'directory).'
         )
-        c_sos_create.add_argument('-s', '--since', help='Create sos-report with logs since n days. e.g. "3days"')
+        c_sos_create.add_argument('-s', '--since',
+                                  help='Create an SOS report with logs since n days, for example, "3days"')
         c_sos_create.add_argument(
             '-n',
             '--nodes',
             nargs='+',
             type=str,
-            help='Only include the given nodes in the sos-report'
+            help='Only include the specified nodes in the SOS report'
         ).completer = self.node_completer
         c_sos_create.add_argument(
             '-r',
             '--resources',
             nargs='+',
             type=str,
-            help='Only include nodes that have the given resources deployed in the sos-report'
+            help='Only include in the SOS report nodes that have the specified resources deployed.'
         ).completer = self.resource_completer
         c_sos_create.add_argument(
             '-e',
             '--exclude-nodes',
             nargs='+',
             type=str,
-            help='Do not include the given nodes in the sos-report'
+            help='Do not include the specified nodes in the SOS report.'
         ).completer = self.node_completer
         c_sos_create.add_argument(
             '--no-controller',
@@ -1218,7 +1220,7 @@ def setup_commands(self, parser):
         c_spc_report_query = spc_rep_subp.add_parser(
             Commands.Subcommands.Query.LONG,
             aliases=[Commands.Subcommands.Query.SHORT],
-            description='Queries the space reporting string'
+            description='Show a report of monthly storage space tracking for the LINSTOR cluster.'
         )
         c_spc_report_query.add_argument(
             '--from-file',

linstor_client/commands/controller_cmds.py

@@ -83,14 +83,15 @@ def setup_commands(self, parser):
         c_shutdown = con_subp.add_parser(
             Commands.Subcommands.Version.LONG,
             aliases=[Commands.Subcommands.Version.SHORT],
-            description='Prints the linstor controller version'
+            description='Prints the LINSTOR controller version.'
         )
         c_shutdown.set_defaults(func=self.cmd_version)
 
         p_query_max_vlm_size = con_subp.add_parser(
             Commands.Subcommands.QueryMaxVlmSize.LONG,
             aliases=[Commands.Subcommands.QueryMaxVlmSize.SHORT],
-            description='Queries the controller for storage pools maximum volume size.')
+            description='Queries the controller for the maximum volume size of storage pools, given a specified '
+            'replica count.')
         p_query_max_vlm_size.add_argument('-p', '--pastable', action="store_true", help='Generate pastable output')
         p_query_max_vlm_size.add_argument(
             '--storage-pool', '-s',

linstor_client/commands/drbd_setup_cmds.py

@@ -29,7 +29,7 @@ class DrbdOptions(object):
 
     @staticmethod
     def description(_type):
-        return "Set drbd {t} options.  Use --unset-[option_name] to unset.".format(t=_type)
+        return "Set DRBD {t} options on the given LINSTOR object. Use --unset-[option_name] to unset.".format(t=_type)
 
     @staticmethod
     def numeric_symbol(_min, _max, _symbols):

linstor_client/commands/exos_cmds.py

@@ -65,19 +65,19 @@ def setup_commands(self, parser):
         exos_parser = parser.add_parser(
             Commands.EXOS,
             formatter_class=argparse.RawTextHelpFormatter,
-            description='EXOS subcommands'
+            description='Exos subcommands'
         )
 
         exos_subp = exos_parser.add_subparsers(
-            title='EXOS commands',
+            title='Exos commands',
             metavar='',
             description=Commands.Subcommands.generate_desc(subcmds)
         )
 
         # get defaults
         p_get_dflts = exos_subp.add_parser(
             ExosCommands.GetDefaults.LONG,
-            description='Lists the default configuration')
+            description='Lists the default configuration.')
         p_get_dflts.add_argument(
             '-p',
             '--pastable',
@@ -88,7 +88,7 @@ def setup_commands(self, parser):
         # set defaults
         p_set_dftls = exos_subp.add_parser(
             ExosCommands.SetDefaults.LONG,
-            description='Sets the default configuration for all enclosures'
+            description='Sets the default configuration for all enclosures.'
         )
         p_set_dftls.add_argument(
             '--username', type=str, help='Default username')
@@ -129,7 +129,7 @@ def setup_commands(self, parser):
         p_new_encl = exos_subp.add_parser(
             Commands.Subcommands.Create.LONG,
             aliases=[Commands.Subcommands.Create.SHORT],
-            description='Create a new EXOS enclosure'
+            description='Create a new Exos enclosure.'
         )
         self._add_create_mod_args(p_new_encl, True)
         p_new_encl.set_defaults(func=self.create_encl)
@@ -138,7 +138,7 @@ def setup_commands(self, parser):
         p_mod_encl = exos_subp.add_parser(
             Commands.Subcommands.Modify.LONG,
             aliases=[Commands.Subcommands.Modify.SHORT],
-            description='Modifies the given EXOS enclosure'
+            description='Modifies the specified Exos enclosure.'
         )
         self._add_create_mod_args(p_mod_encl, False)
         p_mod_encl.set_defaults(func=self.modify_encl)
@@ -147,7 +147,7 @@ def setup_commands(self, parser):
         p_del_encl = exos_subp.add_parser(
             Commands.Subcommands.Delete.LONG,
             aliases=[Commands.Subcommands.Delete.SHORT],
-            description='Deletes the given EXOS enclosure'
+            description='Deletes the specified Exos enclosure.'
         )
         p_del_encl.add_argument(
             'name',
@@ -160,7 +160,7 @@ def setup_commands(self, parser):
         p_list_encl = exos_subp.add_parser(
             Commands.Subcommands.List.LONG,
             aliases=[Commands.Subcommands.List.SHORT],
-            description='Lists the given EXOS enclosure'
+            description='Lists the Exos enclosures known to LINSTOR.'
         )
         p_list_encl.add_argument(
             '--nocache',
@@ -177,7 +177,7 @@ def setup_commands(self, parser):
         p_events_encl = exos_subp.add_parser(
             ExosCommands.Events.LONG,
             aliases=[ExosCommands.Events.SHORT],
-            description='Lists events from both given EXOS controllers'
+            description='Lists events from the controllers in the specified Exos enclosure.'
         )
         p_events_encl.add_argument(
             'name',
@@ -194,7 +194,7 @@ def setup_commands(self, parser):
         # exec
         p_exec = exos_subp.add_parser(
             ExosCommands.Exec.LONG,
-            description="Passthrough to the EXOS API"
+            description="Pass Exos API command(s) to the specified Exos enclosure."
         )
         p_exec.add_argument(
             'name',
@@ -211,8 +211,8 @@ def setup_commands(self, parser):
         # map
         p_map = exos_subp.add_parser(
             ExosCommands.Map.LONG,
-            description='Lists to which Exos controller.ports each Linstor \
-                 node is connected')
+            description='Lists to which Exos controller.ports each LINSTOR \
+                 node is connected.')
         p_map.add_argument('-p', '--pastable', action="store_true",
                            help='Generate pastable output')
         p_map.set_defaults(func=self.exos_map)
@@ -227,36 +227,36 @@ def _add_create_mod_args(self, sub_parser, create=True):
         )
         sub_parser.add_argument(
             'ctrl_a_ip' if create else '--ctrl-a-ip',
-            help='IP address of the first EXOS controller',
+            help='IP address of the first Exos controller',
             # nargs = 1 if create else '?',
             type=str
         )
         sub_parser.add_argument(
             'ctrl_b_ip' if create else '--ctrl-b-ip',
-            help='IP address of the second EXOS controller',
+            help='IP address of the second Exos controller',
             nargs='?' if create else 1,
             type=str
         )
         sub_parser.add_argument(
             '--username',
-            help='Username for this EXOS enclosure',
+            help='Username for this Exos enclosure',
             type=str
         )
         sub_parser.add_argument(
             '--username-env',
-            help='Environment variable containing the username for this EXOS \
+            help='Environment variable containing the username for this Exos \
                 enclosure',
             type=str
         )
         sub_parser.add_argument(
             '--password',
-            help='Password for this EXOS enclosure',
+            help='Password for this Exos enclosure',
             nargs='?',
             type=str
         )
         sub_parser.add_argument(
             '--password-env',
-            help='Environment variable containing the username for this EXOS \
+            help='Environment variable containing the username for this Exos \
                 enclosure',
             type=str
         )

linstor_client/commands/file_cmds.py

@@ -46,14 +46,14 @@ def setup_commands(self, parser):
         p_file_list = file_subp.add_parser(
             Commands.Subcommands.List.LONG,
             aliases=[Commands.Subcommands.List.SHORT],
-            description='Lists all files in the cluster')
-        p_file_list.add_argument('-p', '--pastable', action="store_true", help='Generate pastable output')
+            description='Lists all files in the cluster.')
+        p_file_list.add_argument('-p', '--pastable', action="store_true", help='Generate pastable output.')
         p_file_list.set_defaults(func=self.list)
 
         p_file_show = file_subp.add_parser(
             Commands.Subcommands.Show.LONG,
             aliases=[Commands.Subcommands.Show.SHORT],
-            description='Show a single file, including its content')
+            description='Show a single file, including its content.')
         p_file_show.add_argument(
             'file_name',
             type=str,
@@ -63,7 +63,7 @@ def setup_commands(self, parser):
         p_file_modify = file_subp.add_parser(
             Commands.Subcommands.Modify.LONG,
             aliases=[Commands.Subcommands.Modify.SHORT],
-            description='Modify the contents of a file')
+            description='Modify the contents of a file.')
         p_file_modify.add_argument(
             'file_name',
             type=str,
@@ -73,7 +73,7 @@ def setup_commands(self, parser):
         p_file_delete = file_subp.add_parser(
             Commands.Subcommands.Delete.LONG,
             aliases=[Commands.Subcommands.Delete.SHORT],
-            description='Delete a file')
+            description='Delete a file.')
         p_file_delete.add_argument(
             'file_name',
             type=str,
@@ -83,7 +83,7 @@ def setup_commands(self, parser):
         p_file_deploy = file_subp.add_parser(
             Commands.Subcommands.Deploy.LONG,
             aliases=[Commands.Subcommands.Deploy.SHORT],
-            description='Deploy a file with a resource definition')
+            description='Deploy a file with a resource definition.')
         p_file_deploy.add_argument(
             'file_name',
             type=str,
@@ -97,15 +97,15 @@ def setup_commands(self, parser):
         p_file_undeploy = file_subp.add_parser(
             Commands.Subcommands.Undeploy.LONG,
             aliases=[Commands.Subcommands.Undeploy.SHORT],
-            description='Undeploy a file with a resource definition')
+            description='Undeploy a file from a resource definition.')
         p_file_undeploy.add_argument(
             'file_name',
             type=str,
             help='Name of the file to undeploy')
         p_file_undeploy.add_argument(
             'resource_name',
             type=str,
-            help='Name of the resource definition to undeploy the file with')
+            help='Name of the resource definition to undeploy the file from')
         p_file_undeploy.set_defaults(func=self.undeploy)
 
         self.check_subcommands(file_subp, subcmds)