Merge pull request 'Templates/cli: improve ux and docs' (#4317) from templates-1 into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/4317

docs/site/guides/getting-started/deploy.md

@@ -153,7 +153,7 @@ By default clan uses [disko](https://github.com/nix-community/disko) which allow
 To setup a disk schema for a machine run
 
 ```bash
-clan templates apply disk --to-machine jon --template single-disk --set mainDisk ""
+clan templates apply disk single-disk jon --set mainDisk ""
 ```
 
 Which should fail and give the valid options for the specific hardware:
@@ -166,7 +166,7 @@ Invalid value  for placeholder mainDisk - Valid options:
 Re-run the command with the correct disk:
 
 ```bash
-clan templates apply disk --to-machine jon --template single-disk --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368"
+clan templates apply disk single-disk jon --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368"
 ```
 
 Should now be succesfull

pkgs/clan-cli/clan_cli/__init__.py

@@ -199,6 +199,26 @@ For more detailed information, visit: {help_hyperlink("getting-started", "https:
     parser_templates = subparsers.add_parser(
         "templates",
         help="Interact with templates",
+        description="Interact with templates",
+        epilog=(
+            """
+This subcommand provides an interface to templates provided by clan.
+
+Examples:
+
+  $ clan templates list
+  List all the machines managed by Clan.
+
+  $ clan templates apply disk [TEMPLATE] [MACHINE]
+  Will apply the specified [TEMPLATE] to the [MACHINE]
+
+  Many templates require to *set* variables via the `--set` flag.
+  $ clan templates apply disk [TEMPLATE] [MACHINE] --set key1 value1 --set key2 value2
+
+  Real world example
+  $ clan templates apply disk single-disk jon --set mainDisk "/dev/disk/by-id/nvme-WD_PC_SN740_SDDQNQD-512G-1201_232557804368"
+"""
+        ),
         formatter_class=argparse.RawTextHelpFormatter,
     )
     templates.register_parser(parser_templates)

pkgs/clan-cli/clan_cli/templates/apply_disk.py

@@ -37,29 +37,27 @@ def apply_command(args: argparse.Namespace) -> None:
     placeholders = dict(set_tuples)
 
     set_machine_disk_schema(
-        Machine(args.to_machine, args.flake),
+        Machine(args.machine, args.flake),
         args.template,
         placeholders,
         force=args.force,
         check_hw=not args.skip_hardware_check,
     )
-    log.info(f"Applied disk template '{args.template}' to machine '{args.to_machine}' ")
+    log.info(f"Applied disk template '{args.template}' to machine '{args.machine}' ")
 
 
 def register_apply_disk_template_parser(parser: argparse.ArgumentParser) -> None:
-    machine_action = parser.add_argument(
-        "--to-machine",
+    parser.add_argument(
+        "template",
+        type=str,
+        help="The name of the disk template to apply",
+    )
+    machine_action = parser.add_argument(
+        "machine",
         type=str,
-        required=True,
         help="The machine to apply the template to",
     )
     add_dynamic_completer(machine_action, complete_machines)
-    parser.add_argument(
-        "--template",
-        type=str,
-        required=True,
-        help="The name of the disk template to apply",
-    )
     parser.add_argument(
         "--set",
         help="Set a placeholder in the template to a value",

pkgs/clan-cli/clan_lib/api/disk.py

@@ -188,7 +188,7 @@ def set_machine_disk_schema(
     # check that all required placeholders are present
     for placeholder_name, schema_placeholder in disk_schema.placeholders.items():
         if schema_placeholder.required and placeholder_name not in placeholders:
-            msg = f"Required placeholder {placeholder_name} - {schema_placeholder} missing"
+            msg = f"Required to set template variable {placeholder_name}"
             raise ClanError(msg)
 
     # For every placeholder check that the value is valid