flake-exports: add options documentation

lib/modules/clan/interface.nix

@@ -70,9 +70,13 @@ in
     # TODO: make this writable by moving the options from inventoryClass into clan.
     exports = lib.mkOption {
       readOnly = true;
+      visible = false;
+      internal = true;
     };
 
     exportsModule = lib.mkOption {
+      internal = true;
+      visible = false;
       type = types.deferredModule;
       # can be set only once
       readOnly = true;

lib/modules/inventory/distributed-service/service-module.nix

@@ -104,6 +104,13 @@ let
 in
 {
   options = {
+    # Option to disable some behavior during docs rendering
+    _docs_rendering = mkOption {
+      default = false;
+      visible = false;
+      type = types.bool;
+    };
+
     instances = mkOption {
       visible = false;
       defaultText = "Throws: 'The service must define its instances' when not defined";
@@ -387,6 +394,29 @@ in
                         options.exports = mkOption {
                           type = types.deferredModule;
                           default = { };
+                          description = ''
+                            export modules defined in 'perInstance'
+                            mapped to their instance name
+
+                            Example
+
+                            with instances:
+
+                            ```nix
+                            instances.A = { ... };
+                            instances.B= { ... };
+
+                            roles.peer.perInstance = { instanceName, machine, ... }:
+                            {
+                              exports.foo = 1;
+                            }
+
+                            This yields all other services can access these exports
+                            =>
+                            exports.instances.A.foo = 1;
+                            exports.instances.B.foo = 1;
+                            ```
+                          '';
                         };
                         options.nixosModule = mkOption {
                           type = types.deferredModule;
@@ -521,6 +551,28 @@ in
             options.exports = mkOption {
               type = types.deferredModule;
               default = { };
+              description = ''
+                export modules defined in 'perMachine'
+                mapped to their machine name
+
+                Example
+
+                with machines:
+                ```nix
+                instances.A = { roles.peer.machines.jon = ... };
+                instances.B = { roles.peer.machines.jon = ... };
+
+                perMachine = { machine, ... }:
+                {
+                  exports.foo = 1;
+                }
+
+                This yields all other services can access these exports
+                =>
+                exports.machines.jon.foo = 1;
+                exports.machines.sara.foo = 1;
+                ```
+              '';
             };
             options.nixosModule = mkOption {
               type = types.deferredModule;
@@ -618,30 +670,92 @@ in
     };
 
     exports = mkOption {
+      description = ''
+        This services exports.
+        Gets merged with all other services exports
+
+        Final value (merged and evaluated with other services) available as `exports'` in the arguments of this module.
+
+        ```nix
+        { exports', ... }: {
+          _class = "clan.service";
+          # ...
+        }
+        ```
+      '';
       default = { };
       type = types.submoduleWith {
         # Static modules
-        modules =
+        modules = [
-          [
+          {
-            {
+            options.instances = mkOption {
-              options.instances = mkOption {
+              type = types.attrsOf types.deferredModule;
-                type = types.attrsOf types.deferredModule;
+              description = ''
-              };
+                export modules defined in 'perInstance'
-            }
+                mapped to their instance name
-            {
+
-              options.machines = mkOption {
+                Example
-                type = types.attrsOf types.deferredModule;
+
-              };
+                with instances:
-            }
+
-          ]
+                ```nix
-          ++ lib.mapAttrsToList (_roleName: role: {
+                instances.A = { ... };
-            instances = lib.mapAttrs (_instanceName: instance: {
+                instances.B= { ... };
-              imports = lib.mapAttrsToList (_machineName: v: v.exports) instance.allMachines;
+
-            }) role.allInstances;
+                roles.peer.perInstance = { instanceName, machine, ... }:
-          }) config.result.allRoles
+                {
-          ++ lib.mapAttrsToList (machineName: machine: {
+                  exports.foo = 1;
-            machines.${machineName} = machine.exports;
+                }
-          }) config.result.allMachines;
+
+                This yields all other services can access these exports
+                =>
+                exports.instances.A.foo = 1;
+                exports.instances.B.foo = 1;
+                ```
+              '';
+            };
+            options.machines = mkOption {
+              type = types.attrsOf types.deferredModule;
+              description = ''
+                export modules defined in 'perMachine'
+                mapped to their machine name
+
+                Example
+
+                with machines:
+
+                ```nix
+                instances.A = { roles.peer.machines.jon = ... };
+                instances.B = { roles.peer.machines.jon = ... };
+
+                perMachine = { machine, ... }:
+                {
+                  exports.foo = 1;
+                }
+
+                This yields all other services can access these exports
+                =>
+                exports.machines.jon.foo = 1;
+                exports.machines.sara.foo = 1;
+                ```
+              '';
+            };
+            # Lazy default via imports
+            # should probably be moved to deferredModuleWith { staticModules = [ ]; }
+            imports =
+              if config._docs_rendering then
+                [ ]
+              else
+                lib.mapAttrsToList (_roleName: role: {
+                  instances = lib.mapAttrs (_instanceName: instance: {
+                    imports = lib.mapAttrsToList (_machineName: v: v.exports) instance.allMachines;
+                  }) role.allInstances;
+                }) config.result.allRoles
+                ++ lib.mapAttrsToList (machineName: machine: {
+                  machines.${machineName} = machine.exports;
+                }) config.result.allMachines;
+          }
+        ];
       };
     };
     # ---

lib/modules/inventory/flake-module.nix

@@ -47,7 +47,7 @@ in
         (pkgs.nixosOptionsDoc {
           options =
             (self.clanLib.evalService {
-              modules = [ ];
+              modules = [ { _docs_rendering = true; } ];
               prefix = [ ];
             }).options;
           warningsAreErrors = true;