From 0d555df9ac7e0c99f91b7e37efe5d9c4f71eb7b1 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Thu, 21 Nov 2024 13:41:34 +0100
Subject: [PATCH] Docs/inventory: ad-hoc loading of user modules

---
 docs/site/clanmodules/index.md              | 40 ++++++++++++++++-----
 lib/eval-clan-modules/default.nix           |  2 +-
 lib/inventory/build-inventory/interface.nix | 32 +++++++++++++++--
 3 files changed, 62 insertions(+), 12 deletions(-)

diff --git a/docs/site/clanmodules/index.md b/docs/site/clanmodules/index.md
index 8434cbce7..0d650f979 100644
--- a/docs/site/clanmodules/index.md
+++ b/docs/site/clanmodules/index.md
@@ -6,10 +6,8 @@ This site will guide you through authoring your first module. Explaining which c
 Under construction
 :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier: :fontawesome-solid-road-barrier:
 
-!!! Note
-    Currently ClanModules should be contributed to the [clan-core repository](https://git.clan.lol/clan/clan-core) via a PR.
-
-    Ad-hoc loading of custom modules is not recommended / supported yet.
+!!! Tip
+    External ClanModules can be ad-hoc loaded via [`clan.inventory.modules`](../reference/nix-api/inventory.md#modules)
 
 ## Bootstrapping the `clanModule`
 
@@ -43,13 +41,37 @@ clanModules/borgbackup
 
     The `roles` folder is strictly required for `features = [ "inventory" ]`.
 
-The clanModule must be registered via the `clanModules` attribute in `clan-core`
+=== "User module"
 
-```nix title="clanModules/flake-module.nix"
---8<-- "clanModules/flake-module.nix:0:6"
-    # Register your new module here
+    If the module should be ad-hoc loaded.
+    It can be made avilable in any project via the [`clan.inventory.modules`](../reference/nix-api/inventory.md#modules) attribute.
+
+    ```nix title="flake.nix"
     # ...
-```
+    buildClan {
+        # 1. Add the module to the avilable inventory modules
+        inventory.modules = {
+            custom-module = ./modules/my_module;
+        };
+        # 2. Use the module in the inventory
+        inventory.services = {
+            custom-module.instance_1 = {
+                roles.default.machines = [ "machineA" ];
+            };
+        };
+    };
+    ```
+
+=== "Upstream module"
+
+    If the module will be contributed to [`clan-core`](https://git.clan.lol/clan-core)
+    The clanModule must be registered within the `clanModules` attribute in `clan-core`
+
+    ```nix title="clanModules/flake-module.nix"
+    --8<-- "clanModules/flake-module.nix:0:5"
+        # Register our new module here
+        # ...
+    ```
 
 ## Readme
 
diff --git a/lib/eval-clan-modules/default.nix b/lib/eval-clan-modules/default.nix
index 393d3cab8..b12e910de 100644
--- a/lib/eval-clan-modules/default.nix
+++ b/lib/eval-clan-modules/default.nix
@@ -58,7 +58,7 @@ let
       res = builtins.mapAttrs (
         moduleName: module:
         let
-          frontmatter = clan-core.lib.modules.getFrontmatter moduleName;
+          frontmatter = clan-core.lib.modules.getFrontmatter allModules.${moduleName} moduleName;
           roles =
             if builtins.elem "inventory" frontmatter.features or [ ] then
               assert lib.isPath module;
diff --git a/lib/inventory/build-inventory/interface.nix b/lib/inventory/build-inventory/interface.nix
index cad9ad055..3e152f424 100644
--- a/lib/inventory/build-inventory/interface.nix
+++ b/lib/inventory/build-inventory/interface.nix
@@ -94,10 +94,38 @@ in
   options = {
     modules = lib.mkOption {
       type = types.attrsOf types.path;
-      internal = true;
-      visible = false;
       default = { };
       defaultText = "clanModules of clan-core";
+      description = ''
+        A mapping of module names to their path.
+
+        Each module can be referenced by its `attributeName` in the `inventory.services` attribute set.
+
+        !!! Important
+            Each module MUST fullfill the following requirements to be usable with the inventory:
+
+            - The module MUST have a `README.md` file with a `description`.
+            - The module MUST have at least `features = [ "inventory" ]` in the frontmatter section.
+            - The module MUST have a subfolder `roles` with at least one `{roleName}.nix` file.
+
+            For further information see: [Module Authoring Guide](../../clanmodules/index.md).
+
+        ???+ example
+            ```nix
+            buildClan {
+                # 1. Add the module to the avilable inventory modules
+                inventory.modules = {
+                  custom-module = ./modules/my_module;
+                };
+                # 2. Use the module in the inventory
+                inventory.services = {
+                  custom-module.instance_1 = {
+                      roles.default.machines = [ "machineA" ];
+                  };
+                };
+            };
+            ```
+      '';
     };
 
     assertions = lib.mkOption {