Docs: add inventory module docs

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 ""