Docs/frontmatter: init automatic reference for frontmatter

lib/constraints/interface.nix

@@ -18,6 +18,9 @@ in
   options.roles = lib.mapAttrs (
     _name: _:
     mkOption {
+      description = ''
+        Sub-attributes of `${_name}` are constraints for the role.
+      '';
       default = { };
       type = types.submoduleWith {
         modules = [
@@ -26,10 +29,16 @@ in
               max = mkOption {
                 type = types.nullOr types.int;
                 default = null;
+                description = ''
+                  Maximum number of instances of this role that can be assigned to a module of this type.
+                '';
               };
               min = mkOption {
                 type = types.int;
                 default = 0;
+                description = ''
+                  Minimum number of instances of this role that must at least be assigned to a module of this type.
+                '';
               };
             };
           }

lib/frontmatter/default.nix

@@ -20,17 +20,16 @@ let
       ];
     };
 
-  frontmatterDocsOptions =
-    lib.optionAttrSetToDocList
-      (lib.evalModules {
-        specialArgs = {
-          moduleName = "{moduleName}";
-          allRoles = [ "{roleName}" ];
-        };
-        modules = [
-          ./interface.nix
-        ];
-      }).options;
+  frontmatterOptions =
+    (lib.evalModules {
+      specialArgs = {
+        moduleName = "{moduleName}";
+        allRoles = [ "{roleName}" ];
+      };
+      modules = [
+        ./interface.nix
+      ];
+    }).options;
 
   getRoles =
     serviceName:
@@ -91,7 +90,7 @@ in
 {
   inherit
     evalFrontmatter
-    frontmatterDocsOptions
+    frontmatterOptions
 
     getFrontmatter
     getReadme

lib/frontmatter/interface.nix

@@ -11,11 +11,16 @@ in
     description = mkOption {
       type = types.str;
       description = ''
-
+        A Short description of the module.
       '';
     };
     categories = mkOption {
       default = [ "Uncategorized" ];
+      description = ''
+        Categories are used for Grouping and searching.
+
+        While initial oriented on [freedesktop](https://specifications.freedesktop.org/menu-spec/latest/category-registry.html) the following categories are allowed
+      '';
       type = types.listOf (
         types.enum [
           "AudioVideo"
@@ -38,6 +43,15 @@ in
     };
     features = mkOption {
       default = [ ];
+      description = ''
+        Clans Features that the module implements support for.
+
+        !!! warning "Important"
+            Every ClanModule, that specifies `features = [ "inventory" ]` MUST have at least one role.
+            Many modules use `roles/default.nix` which registers the role `default`.
+
+            If you are a clan module author and your module has only one role where you cannot determine the name, then we would like you to follow the convention.
+      '';
       type = types.listOf (
         types.enum [
           "inventory"
@@ -47,6 +61,19 @@ in
 
     constraints = mkOption {
       default = { };
+      description = ''
+        Contraints for the module
+
+        The following example requires exactly one `server`
+        and supports up to `7` clients
+
+        ```md
+        ---
+        constraints.roles.server.eq = 1
+        constraints.roles.client.max = 7
+        ---
+        ```
+      '';
       type = types.submoduleWith {
         inherit specialArgs;
         modules = [

lib/inventory/schemas/default.nix

@@ -22,6 +22,8 @@ let
     header = { };
   };
 
+  frontMatterSchema = jsonLib.parseOptions self.lib.modules.frontmatterOptions { };
+
   inventorySchema = jsonLib.parseModule (import ../build-inventory/interface.nix);
 
   renderSchema = pkgs.writers.writePython3Bin "render-schema" {
@@ -48,6 +50,7 @@ let
 in
 {
   inherit
+    frontMatterSchema
     inventorySchema
     modulesSchema
     renderSchema