nixos tests: add documentation machine

checks/nixos-documentation/flake-module.nix

@@ -6,6 +6,8 @@ let
     documentation.nixos.enable = true;
     documentation.nixos.extraModules = [
       self.nixosModules.clanCore
+      # This is the only option that is not part of the
+      # module because it is usually set by flake-parts
       { clan.core.clanDir = ./.; }
     ];
   };

nixosModules/clanCore/inventory/interface.nix

@@ -14,22 +14,49 @@ let
   #   };
   # }
   instanceOptions = lib.types.submodule {
-    options.roles = lib.mkOption { type = lib.types.attrsOf machinesList; };
+    options.roles = lib.mkOption {
+      description = ''
+        Configuration for a service instance.
+
+        Specific roles describe the membership of foreign machines.
+
+        ```nix
+        { # Configuration for an instance
+          roles.<roleName>.machines = [ # List of machines ];
+        }
+        ```
+      '';
+
+      type = lib.types.attrsOf machinesList;
+    };
   };
 
-  # {
-  #   machines = [
-  #     "camina_machine"
-  #     "vi_machine"
-  #     "vyr_machine"
-  #   ];
-  # }
   machinesList = lib.types.submodule {
-    options.machines = lib.mkOption { type = lib.types.listOf lib.types.str; };
+    options.machines = lib.mkOption {
+      description = ''
+        List of machines that are part of a role.
+
+        ```nix
+        { # Configuration for an instance
+          roles.<roleName>.machines = [ # List of machines ];
+        }
+        ```
+      '';
+      type = lib.types.listOf lib.types.str;
+    };
   };
 in
 {
   options.clan.inventory.services = lib.mkOption {
+    description = ''
+      Configuration for each inventory service.
+
+      Each service can have multiple instances as follows:
+
+      ```
+      {serviceName}.{instancename} = { # Configuration for an instance }
+      ```
+    '';
     type = lib.types.attrsOf (lib.types.attrsOf instanceOptions);
   };
 }

nixosModules/clanCore/meta/interface.nix

@@ -3,7 +3,16 @@ let
   optStr = lib.types.nullOr lib.types.str;
 in
 {
-  options.clan.meta.name = lib.mkOption { type = lib.types.str; };
+  options.clan.meta.name = lib.mkOption {
-  options.clan.meta.description = lib.mkOption { type = optStr; };
+    description = "The name of the clan";
-  options.clan.meta.icon = lib.mkOption { type = optStr; };
+    type = lib.types.str;
+  };
+  options.clan.meta.description = lib.mkOption {
+    description = "The description of the clan";
+    type = optStr;
+  };
+  options.clan.meta.icon = lib.mkOption {
+    description = "The location of the clan icon";
+    type = optStr;
+  };
 }