vars: generate docs for cli and module

docs/mkdocs.yml

@@ -120,6 +120,7 @@ nav:
           - reference/cli/show.md
           - reference/cli/ssh.md
           - reference/cli/state.md
+          - reference/cli/vars.md
           - reference/cli/vms.md
       - Clan Core:
           - reference/clan-core/index.md
@@ -130,6 +131,7 @@ nav:
           - reference/clan-core/state.md
           - reference/clan-core/deployment.md
           - reference/clan-core/networking.md
+          - reference/clan-core/vars.md
       - Nix API:
           - buildClan: reference/nix-api/buildclan.md
           - Inventory: reference/nix-api/inventory.md

nixosModules/clanCore/vars/default.nix

@@ -22,7 +22,6 @@ in
     # ./secret/vm.nix
   ];
   options.clan.core.vars = lib.mkOption {
-    visible = false;
     description = ''
       Generated Variables
 

nixosModules/clanCore/vars/interface.nix

@@ -54,6 +54,7 @@ in
               '';
               readOnly = true;
               default = generator.config._module.args.name;
+              defaultText = "Name of the generator";
             };
 
             dependencies = lib.mkOption {
@@ -91,7 +92,10 @@ in
                     # lists are not allowed as of now due to potential ordering issues
                   ]);
                 in
-                data;
+                data
+                // {
+                  description = "JSON compatible data structure";
+                };
             };
             # the invalidationHash is the validation interface to the outside world
             invalidationHash = lib.mkOption {
@@ -108,6 +112,7 @@ in
                   null
                 else
                   hashString "sha256" (toJSON generator.config.invalidationData);
+              defaultText = "Hash of the invalidation data";
             };
             files = lib.mkOption {
               description = ''
@@ -145,6 +150,7 @@ in
                       '';
                       readOnly = true;
                       default = file.config._module.args.name;
+                      defaultText = "Name of the file";
                     };
                     generatorName = lib.mkOption {
                       type = lib.types.str;
@@ -153,6 +159,7 @@ in
                       '';
                       readOnly = true;
                       default = generator.config._module.args.name;
+                      defaultText = "Name of the generator that generates this file";
                     };
                     share = lib.mkOption {
                       type = lib.types.bool;
@@ -164,6 +171,7 @@ in
                       readOnly = true;
                       internal = true;
                       default = generator.config.share;
+                      defaultText = "Mirror of the share flag of the generator";
                     };
                     deploy = lib.mkOption {
                       description = ''
@@ -229,6 +237,7 @@ in
                       '';
                       type = str;
                       default = prompt.config._module.args.name;
+                      defaultText = "Name of the prompt";
                     };
                     createFile = lib.mkOption {
                       description = ''
@@ -252,6 +261,7 @@ in
                       type = str;
                       example = "SSH private key";
                       default = prompt.config._module.args.name;
+                      defaultText = "Name of the prompt";
                     };
                     type = lib.mkOption {
                       description = ''
@@ -301,7 +311,6 @@ in
               type = lib.types.str;
               readOnly = true;
               internal = true;
-              visible = false;
             };
             share = lib.mkOption {
               description = ''

pkgs/clan-cli/clan_cli/__init__.py

@@ -293,11 +293,11 @@ For more detailed information, visit: {help_hyperlink("secrets", "https://docs.c
     # like facts but with vars instead of facts
     parser_vars = subparsers.add_parser(
         "vars",
-        help="WIP: Manage vars",
-        description="WIP: Manage vars",
+        help="Manage vars",
+        description="Manage vars",
         epilog=(
             f"""
-This subcommand provides an interface to vars of clan machines.
+This subcommand provides an interface to `vars` of clan machines.
 Vars are variables that a service can generate.
 There are public and secret vars.
 Public vars can be referenced by other machines directly.

pkgs/clan-cli/clan_cli/machines/machines.py

@@ -137,7 +137,6 @@ class Machine:
         module = importlib.import_module(self.public_facts_module)
         return module.FactStore(machine=self)
 
-    # WIP: Vars module is not ready yet.
     @property
     def secret_vars_module(self) -> str:
         return self.deployment["vars"]["secretModule"]

pkgs/clan-cli/clan_cli/vars/generate.py

@@ -487,7 +487,7 @@ def generate_command(args: argparse.Namespace) -> None:
         machines = get_all_machines(args.flake, args.option)
     else:
         machines = get_selected_machines(args.flake, args.option, args.machines)
-    generate_vars(machines, args.service, args.regenerate, args.fix)
+    generate_vars(machines, args.generator, args.regenerate, args.fix)
 
 
 def register_generate_parser(parser: argparse.ArgumentParser) -> None:
@@ -501,15 +501,17 @@ def register_generate_parser(parser: argparse.ArgumentParser) -> None:
     add_dynamic_completer(machines_parser, complete_machines)
 
     service_parser = parser.add_argument(
-        "--service",
+        "--generator",
+        "-g",
         type=str,
-        help="service to generate facts for, if empty, generate facts for every service",
+        help="execute only the specified generator. If unset, execute all generators",
         default=None,
     )
     add_dynamic_completer(service_parser, complete_services_for_machine)
 
     parser.add_argument(
         "--regenerate",
+        "-r",
         action=argparse.BooleanOptionalAction,
         help="whether to regenerate facts for the specified machine",
         default=None,