Docs: add inventory module docs

clanModules/borgbackup-static/default.nix

@@ -3,7 +3,7 @@ let
   clanDir = config.clan.core.clanDir;
   machineDir = clanDir + "/machines/";
 in
-lib.warn "This module is deprecated use the service via the service interface instead." {
+lib.warn "This module is deprecated use the service via the inventory interface instead." {
   imports = [ ../borgbackup ];
 
   options.clan.borgbackup-static = {

clanModules/borgbackup/README.md

@@ -1,15 +1,2 @@
 Efficient, deduplicating backup program with optional compression and secure encryption.
----
-
-## Roles
-
-- Client
-- Server
-
-## Configuration
-
-Configure target machines where the backups should be sent to through `targets`.
-
-Configure machines that should be backed up either through `includeMachines`
-which will exclusively add the included machines to be backed up, or through
-`excludeMachines`, which will add every machine except the excluded machine to the backup.
+---

clanModules/borgbackup/default.nix

@@ -30,39 +30,37 @@ let
 
   # Each .nix file in the roles directory is a role
   # TODO: Helper function to set available roles within module meta.
-  # roles = lib.pipe ./roles [
-  #   (p: if builtins.pathExists p then p else throw "Role directory does not exist")
-  #   builtins.readDir
-  #   (lib.filterAttrs (_n: v: v == "regular"))
-  #   lib.attrNames
-  #   (map (fileName: lib.removeSuffix ".nix" fileName))
-  # ];
+  roles =
+    if builtins.pathExists ./roles then
+      lib.pipe ./roles [
+        builtins.readDir
+        (lib.filterAttrs (_n: v: v == "regular"))
+        lib.attrNames
+        (map (fileName: lib.removeSuffix ".nix" fileName))
+      ]
+    else
+      null;
 
   # TODO: make this an interface of every module
   # Maybe load from readme.md
   metaInfoOption = lib.mkOption {
     readOnly = true;
     default = {
-      description = "A category for the service. This is used to group services in the clan ui";
+      description = "Borgbackup is a backup program. Optionally, it supports compression and authenticated encryption.";
+      availableRoles = roles;
+      category = "backup";
     };
     type = lib.types.submodule {
       options = {
-        description = lib.mkOption {
+        description = lib.mkOption { type = lib.types.str; };
+        availableRoles = lib.mkOption { type = lib.types.nullOr (lib.types.listOf lib.types.str); };
+        category = lib.mkOption {
           description = "A category for the service. This is used to group services in the clan ui";
-          type = lib.types.str;
+          type = lib.types.enum [
+            "backup"
+            "network"
+          ];
         };
-        # icon = lib.mkOption {
-        #   description = "A category for the service. This is used to group services in the clan ui";
-        #   type = lib.types.str;
-        # };
-        # screenshots = lib.mkOption {
-        #   description = "A category for the service. This is used to group services in the clan ui";
-        #   type = lib.types.str;
-        # };
-        # category = lib.mkOption {
-        #   description = "A category for the service. This is used to group services in the clan ui";
-        #   type = lib.types.enum ["backup" "network"];
-        # };
       };
     };
   };
@@ -105,11 +103,6 @@ in
   };
 
   imports = [
-    {
-      config.clan.borgbackup.meta = {
-        description = "backup";
-      };
-    }
     (lib.mkRemovedOptionModule [
       "clan"
       "borgbackup"

docs/mkdocs.yml

@@ -49,7 +49,7 @@ nav:
       - Mesh VPN: getting-started/mesh-vpn.md
       - Backup & Restore: getting-started/backups.md
       - Flake-parts: getting-started/flake-parts.md
-  - Modules:
+  - Reference:
       - Clan Modules:
           - reference/clanModules/borgbackup-static.md
           - reference/clanModules/borgbackup.md

docs/nix/flake-module.nix

@@ -19,6 +19,7 @@
 
       clanModulesFileInfo = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModules);
       clanModulesReadmes = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesReadmes);
+      clanModulesMeta = pkgs.writeText "info.json" (builtins.toJSON jsonDocs.clanModulesMeta);
 
       # Simply evaluated options (JSON)
       renderOptions =
@@ -54,6 +55,7 @@
         # A file that contains the links to all clanModule docs
         export CLAN_MODULES=${clanModulesFileInfo}
         export CLAN_MODULES_READMES=${clanModulesReadmes}
+        export CLAN_MODULES_META=${clanModulesMeta}
 
         mkdir $out
 

docs/nix/get-module-docs.nix

@@ -43,11 +43,16 @@ let
     module_name: _module: self.lib.modules.getReadme module_name
   ) clanModules;
 
+  clanModulesMeta = builtins.mapAttrs (
+    module_name: _module:
+    (self.lib.evalClanModules [ module_name ]).config.clan.${module_name}.meta or { }
+  ) clanModules;
+
   # clanCore docs
   clanCoreDocs = (evalDocs (getOptions [ ]).clan.core).optionsJSON;
 in
 {
-  inherit clanModulesReadmes;
+  inherit clanModulesReadmes clanModulesMeta;
   clanCore = clanCoreDocs;
   clanModules = clanModulesDocs;
 }

docs/nix/scripts/renderOptions.py

@@ -32,6 +32,8 @@ from typing import Any
 CLAN_CORE = os.getenv("CLAN_CORE")
 CLAN_MODULES = os.environ.get("CLAN_MODULES")
 CLAN_MODULES_READMES = os.environ.get("CLAN_MODULES_READMES")
+CLAN_MODULES_META = os.environ.get("CLAN_MODULES_META")
+
 
 OUT = os.environ.get("out")
 
@@ -198,6 +200,11 @@ def produce_clan_modules_docs() -> None:
             f"Environment variables are not set correctly: $CLAN_MODULES_READMES={CLAN_MODULES_READMES}"
         )
 
+    if not CLAN_MODULES_META:
+        raise ValueError(
+            f"Environment variables are not set correctly: $CLAN_MODULES_META={CLAN_MODULES_META}"
+        )
+
     if not OUT:
         raise ValueError(f"Environment variables are not set correctly: $out={OUT}")
 
@@ -207,6 +214,42 @@ def produce_clan_modules_docs() -> None:
     with open(CLAN_MODULES_READMES) as readme:
         readme_map: dict[str, str] = json.load(readme)
 
+    with open(CLAN_MODULES_META) as f:
+        meta_map: dict[str, Any] = json.load(f)
+        print(meta_map)
+
+    def render_meta(meta: dict[str, Any], module_name: str) -> str:
+        roles = meta.get("availableRoles", None)
+
+        if roles:
+            roles_list = "\n".join([f"    - `{r}`" for r in roles])
+            return f"""
+???+ tip "Inventory (WIP)"
+
+    Predefined roles:
+
+{roles_list}
+
+    Usage:
+
+    ```{{.nix hl_lines="4"}}
+    buildClan {{
+      inventory.services = {{
+        {module_name}.instance_1 = {{
+            roles.{roles[0]}.machines = [ "sara_machine" ];
+            # ...
+        }};
+      }};
+    }}
+    ```
+
+"""
+        return """
+???+ example "Inventory (WIP)"
+    This module does not support the inventory yet.
+
+        """
+
     # {'borgbackup': '/nix/store/hi17dwgy7963ddd4ijh81fv0c9sbh8sw-options.json', ... }
     for module_name, options_file in links.items():
         with open(Path(options_file) / "share/doc/nixos/options.json") as f:
@@ -217,6 +260,10 @@ def produce_clan_modules_docs() -> None:
             if readme_map.get(module_name, None):
                 output += f"{readme_map[module_name]}\n"
 
+            # Add meta information:
+            # - Inventory implementation status
+            output += render_meta(meta_map.get(module_name, {}), module_name)
+
             output += module_usage(module_name)
 
             output += options_head if len(options.items()) else ""