help: standardize command descriptions

This enables us to use the same wording on the manpage, docs, and help calls. Signed-off-by: Renan Rodrigo <[email protected]>
canonical · Sep 3, 2024 · cdc8f3b · cdc8f3b
1 parent 8aad71b
commit cdc8f3b
Show file tree

Hide file tree

Showing 6 changed files with 131 additions and 69 deletions.
diff --git a/features/cli/help.feature b/features/cli/help.feature
@@ -39,6 +39,7 @@ Feature: Pro Client help text
       usage: pro collect-logs [-h] [-o OUTPUT]
 
       Collect logs and relevant system information into a tarball.
+      This information can be later used for triaging/debugging issues.
 
       <options_string>:
         -h, --help            show this help message and exit
@@ -54,6 +55,11 @@ Feature: Pro Client help text
 
       Calls the Client API endpoints.
 
+      For a list of all of the supported endpoints and their structure,
+      please refer to the Pro Client API reference guide:
+
+      https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/references/api/
+
       positional arguments:
         endpoint              API endpoint to call
 
@@ -94,7 +100,7 @@ Feature: Pro Client help text
                         [--format {cli,json}] [--variant VARIANT]
                         service [service ...]
 
-      Enable an Ubuntu Pro service.
+      Activate and configure this machine's access to an Ubuntu Pro service.
 
       positional arguments:
         service              the name(s) of the Ubuntu Pro services to enable. One
@@ -127,6 +133,16 @@ Feature: Pro Client help text
       and prompt you to attach the machine to your Ubuntu Pro account using
       a web browser.
 
+      The --attach-config option can be used to provide a file with the token
+      and optionally, a list of services to enable after attaching. To know more,
+      visit:
+      https://canonical-ubuntu-pro-client.readthedocs-hosted.com/en/latest/howtoguides/how_to_attach_with_config_file/
+
+      The exit code will be:
+          0: on successful attach
+          1: in case of any error while trying to attach
+          2: if the machine is already attached
+
       positional arguments:
         token                 token obtained for Ubuntu Pro authentication
 
@@ -175,11 +191,12 @@ Feature: Pro Client help text
 
       If called with --format json|yaml it shows a summary of the
       installed packages based on the origin:
-      - main/restricted/universe/multiverse: packages from the Ubuntu archive
-      - esm-infra/esm-apps: packages from the ESM archive
-      - third-party: packages installed from non-Ubuntu sources
-      - unknown: packages which don't have an installation source (like local
-        deb packages or packages for which the source was removed)
+
+          - main/restricted/universe/multiverse: packages from the Ubuntu archive
+          - esm-infra/esm-apps: packages from the ESM archive
+          - third-party: packages installed from non-Ubuntu sources
+          - unknown: packages which don't have an installation source (like local
+            deb packages or packages for which the source was removed)
 
       The output contains basic information about Ubuntu Pro. For a
       complete status on Ubuntu Pro services, run 'pro status'.
@@ -200,7 +217,13 @@ Feature: Pro Client help text
       """
       usage: pro fix [-h] [--dry-run] [--no-related] security_issue
 
-      Inspect and resolve CVEs and USNs (Ubuntu Security Notices) on this machine.
+      Inspect and resolve Common Vulnerabilities and Exposures (CVEs) and
+      Ubuntu Security Notices (USNs) on this machine.
+
+      The exit code will be:
+          0: the fix was successfully applied or the system is not affected
+          1: the fix cannot be applied
+          2: the fix was applied but requires a reboot before it takes effect
 
       positional arguments:
         security_issue  Security vulnerability ID to inspect and resolve on this
@@ -223,28 +246,28 @@ Feature: Pro Client help text
 
       Report current status of Ubuntu Pro services on system.
 
-      This shows whether this machine is attached to an Ubuntu Advantage
+      This shows whether this machine is attached to an Ubuntu Pro
       support contract. When attached, the report includes the specific
       support contract details including contract name, expiry dates, and the
       status of each service on this system.
 
       The attached status output has four columns:
 
-      * SERVICE: name of the service
-      * ENTITLED: whether the contract to which this machine is attached
-        entitles use of this service. Possible values are: yes or no
-      * STATUS: whether the service is enabled on this machine. Possible
-        values are: enabled, disabled, n/a (if your contract entitles
-        you to the service, but it isn't available for this machine) or — (if
-        you aren't entitled to this service)
-      * DESCRIPTION: a brief description of the service
+          * SERVICE: name of the service
+          * ENTITLED: whether the contract to which this machine is attached
+            entitles use of this service. Possible values are: yes or no
+          * STATUS: whether the service is enabled on this machine. Possible
+            values are: enabled, disabled, n/a (if your contract entitles
+            you to the service, but it isn't available for this machine) or — (if
+            you aren't entitled to this service)
+          * DESCRIPTION: a brief description of the service
 
       The unattached status output instead has three columns. SERVICE
       and DESCRIPTION are the same as above, and there is the addition
       of:
 
-      * AVAILABLE: whether this service would be available if this machine
-        were attached. The possible values are yes or no.
+          * AVAILABLE: whether this service would be available if this machine
+            were attached. The possible values are yes or no.
 
       If --simulate-with-token is used, then the output has five
       columns. SERVICE, AVAILABLE, ENTITLED and DESCRIPTION are the same
@@ -270,12 +293,12 @@ Feature: Pro Client help text
 
       Refresh three distinct Ubuntu Pro related artifacts in the system:
 
-      * contract: Update contract details from the server.
-      * config:   Reload the config file.
-      * messages: Update APT and MOTD messages related to UA.
+          * contract: Update contract details from the server.
+          * config:   Reload the config file.
+          * messages: Update APT and MOTD messages related to Pro.
 
       You can individually target any of the three specific actions,
-      by passing the target name to the command.  If no `target`
+      by passing the target name to the command.  If no target
       is specified, all targets are refreshed.
 
       positional arguments:
@@ -290,7 +313,7 @@ Feature: Pro Client help text
       """
       usage: pro system [-h] {reboot-required} ...
 
-      Output system related information related to Pro services
+      Outputs system-related information about Pro services
 
       <options_string>:
         -h, --help         show this help message and exit
@@ -309,13 +332,13 @@ Feature: Pro Client help text
       This command will output one of the three following states
       for the machine regarding reboot:
 
-      * no: The machine doesn't require a reboot
-      * yes: The machine requires a reboot
-      * yes-kernel-livepatches-applied: There are only kernel related
-        packages that require a reboot, but Livepatch has already provided
-        patches for the current running kernel. The machine still needs a
-        reboot, but you can assess if the reboot can be performed in the
-        nearest maintenance window.
+          * no: The machine doesn't require a reboot
+          * yes: The machine requires a reboot
+          * yes-kernel-livepatches-applied: There are only kernel-related
+            packages that require a reboot, but Livepatch has already provided
+            patches for the current running kernel. The machine still needs a
+            reboot, but you can assess if the reboot can be performed in the
+            nearest maintenance window.
 
       <options_string>:
         -h, --help  show this help message and exit
@@ -325,7 +348,7 @@ Feature: Pro Client help text
       """
       usage: pro config [-h] {show,set,unset} ...
 
-      Manage Ubuntu Pro configuration
+      Manage Ubuntu Pro Client configuration on this machine
 
       <options_string>:
         -h, --help        show this help message and exit
@@ -334,7 +357,8 @@ Feature: Pro Client help text
         {show,set,unset}
           show            Show customizable configuration settings
           set             Set and apply Ubuntu Pro configuration settings
-          unset           Unset Ubuntu Pro configuration setting
+          unset           Unset an Ubuntu Pro configuration setting, restoring the
+                          default value.
       """
     When I run `pro config show --help` as non-root
     Then I will see the following on stdout
@@ -372,7 +396,7 @@ Feature: Pro Client help text
       """
       usage: pro config unset [-h] key
 
-      Unset Ubuntu Pro configuration setting
+      Unset an Ubuntu Pro configuration setting, restoring the default value.
 
       positional arguments:
         key         configuration key to unset from Ubuntu Pro services. One of:

diff --git a/uaclient/cli/api.py b/uaclient/cli/api.py
@@ -51,6 +51,7 @@ def action_api(args, *, cfg, **kwargs):
     help=messages.CLI_ROOT_API,
     description=messages.CLI_API_DESC,
     action=action_api,
+    preserve_description=True,
     argument_groups=[
         ProArgumentGroup(
             arguments=[

diff --git a/uaclient/cli/collect_logs.py b/uaclient/cli/collect_logs.py
@@ -28,6 +28,7 @@ def action_collect_logs(args, *, cfg, **kwargs):
     "collect-logs",
     help=messages.CLI_ROOT_COLLECT_LOGS,
     description=messages.CLI_COLLECT_LOGS_DESC,
+    preserve_description=True,
     action=action_collect_logs,
     argument_groups=[
         ProArgumentGroup(

diff --git a/uaclient/cli/fix.py b/uaclient/cli/fix.py
@@ -915,6 +915,7 @@ def action_fix(args, *, cfg, **kwargs):
     help=messages.CLI_ROOT_FIX,
     description=messages.CLI_FIX_DESC,
     action=action_fix,
+    preserve_description=True,
     argument_groups=[
         ProArgumentGroup(
             arguments=[