cli: Improve cloe-launch command help messages

Author: cassava

cli/cloe_launch/commands/activate.py

@@ -60,12 +60,15 @@ def cli_activate(
     \b
     Warnings:
     - If you use method #3 and delete ~/.cache/cloe, you will get errors
-      until you re-create the profile.
+      until you re-create the runtime environment.
     - Deleting or overwriting packages in your Conan cache that are used
       in an activated environment is undefined behavior: it can lead to
       unexpected problems!
-    - Using cloe shell in combination with cloe activate is undefined
-      behavior: it can lead to unexpected problems.
+    - Using cloe shell in combination with cloe activate is currently
+      undefined behavior: it can lead to unexpected problems.
+
+    If you want permanence, it's probably better to use the `deploy`
+    command instead of `activate`.
     """
     engine = Engine(conf, conanfile=conanfile)
     engine.conan_args = options.extract_conan_args(args)

cli/cloe_launch/commands/clean.py

@@ -41,7 +41,32 @@ def cli_clean(
     all: bool,
     conanfile: str,
 ):
-    """Clean launcher runtime environment for specified configuration."""
+    """Clean launcher runtime environment for specified configuration.
+
+    The runtime environment is by default at `~/.cache/cloe/launcher/`
+    in a directory named after a hash calculated from the conanfile.
+    Currently, the hash does not take additional arguments into account
+    (this should change in the future).
+
+    It is safe to clean a configuration or all configurations.
+    Almost all commands will regenerate these configurations if needed
+    within a few seconds. However, the following cases should be noted:
+
+    \b
+    1. If the `deploy` command is used with a configuration,
+       an uninstall script is stored in the cache.
+       This should be preserved if you want to completely
+       remove a deployed configuration at a later time.
+    2. If the output of the `activate` command is used,
+       for example in the `.bashrc` file,
+       then you should not clean the configuration.
+
+    Usage Examples:
+
+    \b
+        cloe-launch clean tests/conanfile.py
+        cloe-launch clean -a
+    """
     engine = Engine(conf, conanfile=conanfile)
 
     if all:

cli/cloe_launch/commands/deploy.py

@@ -68,6 +68,12 @@ def cli_deploy(
 
     This may involve downloading missing and available packages and building
     outdated packages.
+
+    Usage Examples:
+
+    \b
+        cloe-launch deploy -f -D /usr/local tests/conanfile.py
+        cloe-launch deploy -D deploy tests/conanfile.py
     """
     engine = Engine(conf, conanfile=conanfile)
     engine.conan_args = options.extract_conan_args(args)

cli/cloe_launch/commands/exec.py

@@ -54,9 +54,19 @@ def cli_exec(
     conanfile: str,
     args: List[str],
 ):
-    """Launch cloe-engine with a profile.
+    """Launch cloe-engine from a Conan recipe.
 
-    ENGINE_ARGS are passed on to cloe-engine.
+    No options to cloe-launch may appear after specifying the conanfile.
+    All options encountered after the conanfile and before -- will be
+    passed to `conan install`. See `conan install --help` for help on
+    which options are available here. All arguments after -- will be
+    passed to the `cloe-engine` binary.
+
+    Usage Examples:
+
+    \b
+        cloe-launch exec -c tests/conanfile.py -- usage
+        cloe-launch exec -c tests/conanfile.py -- -l debug run tests/smoketest.json
     """
     engine = Engine(conf, conanfile=conanfile)
     engine.conan_args = options.extract_conan_args(args)

cli/cloe_launch/commands/prepare.py

@@ -51,8 +51,9 @@ def cli_prepare(
     passed to `conan install`. See `conan install --help` for help on
     which options are available here.
 
-    Examples:
+    Usage Examples:
 
+    \b
         cloe-launch prepare tests/conanfile.py --build=missing
         cloe-launch prepare tests/conanfile.py -o cloe-engine:server=False --build=outdated
         cloe-launch prepare tests/conanfile.py -s build_type=Debug --build="*/*@cloe/develop"

cli/cloe_launch/commands/shell.py

@@ -46,7 +46,24 @@ def cli_shell(
     conanfile: str,
     args: List[str],
 ):
-    """Launch shell with the correct environment from a profile."""
+    """Launch shell with the correct environment from a profile.
+
+    No options to cloe-launch may appear after specifying the conanfile.
+    All options encountered after the conanfile and before -- will be
+    passed to `conan install`. See `conan install --help` for help on
+    which options are available here. All arguments after -- will be
+    passed to the shell.
+
+    Set the SHELL environment variable to influence which shell will be used.
+
+    Usage Examples:
+
+    \b
+        cloe-launch shell tests/conanfile.py
+        cloe-launch shell -c tests/conanfile.py -- -c "bats tests"
+        cloe-launch shell -E tests/conanfile.py -o cloe-engine:server=False -- -c "bats tests"
+        SHELL=/bin/bash cloe-launch shell tests/conanfile.py
+    """
     engine = Engine(conf, conanfile=conanfile)
     engine.preserve_env = preserve_env
     engine.conan_args = options.extract_conan_args(args)