Merge pull request 'reference docs: add missing description fields and enforce it from now on' (#1704) from DavHau/clan-core:DavHau-dave into main

clanModules/postgresql/default.nix

@@ -91,6 +91,7 @@ in
   options.clan.postgresql = {
     # we are reimplemeting ensureDatabase and ensureUser options here to allow to create databases with options
     databases = lib.mkOption {
+      description = "Databases to create";
       default = { };
       type = lib.types.attrsOf (
         lib.types.submodule (
@@ -114,6 +115,7 @@ in
                 description = "Create the database if it does not exist.";
               };
               create.options = lib.mkOption {
+                description = "Options to pass to the CREATE DATABASE command.";
                 type = lib.types.lazyAttrsOf lib.types.str;
                 default = { };
                 example = {
@@ -135,12 +137,14 @@ in
       );
     };
     users = lib.mkOption {
+      description = "Users to create";
       default = { };
       type = lib.types.attrsOf (
         lib.types.submodule (
           { name, ... }:
           {
             options.name = lib.mkOption {
+              description = "User name";
               type = lib.types.str;
               default = name;
             };

clanModules/syncthing/default.nix

@@ -7,6 +7,10 @@
 {
   options.clan.syncthing = {
     id = lib.mkOption {
+      description = ''
+        The ID of the machine.
+        It is generated automatically by default.
+      '';
       type = lib.types.nullOr lib.types.str;
       example = "BABNJY4-G2ICDLF-QQEG7DD-N3OBNGF-BCCOFK6-MV3K7QJ-2WUZHXS-7DTW4AS";
       default = config.clan.core.facts.services.syncthing.public."syncthing.pub".value or null;

docs/nix/get-module-docs.nix

@@ -30,7 +30,7 @@ let
     options:
     pkgs.nixosOptionsDoc {
       options = options;
-      warningsAreErrors = false;
+      warningsAreErrors = true;
     };
 
   # clanModules docs

nixosModules/clanCore/facts/default.nix

@@ -67,9 +67,19 @@
     publicDirectory = lib.mkOption {
       type = lib.types.nullOr lib.types.path;
       default = null;
+      description = ''
+        The directory where public facts are stored.
+      '';
     };
 
     services = lib.mkOption {
+      description = ''
+        Services to generate secrets and facts for.
+        Each service can have a generator script which generates the secrets and facts.
+        The generator script is expected to generate all secrets and facts defined for this service.
+
+        A `service` does not need to ba analogous to a systemd service, it can be any group of facts and secrets that need to be generated together.
+      '';
       default = { };
       type = lib.types.attrsOf (
         lib.types.submodule (service: {
@@ -82,6 +92,9 @@
               '';
             };
             generator = lib.mkOption {
+              description = ''
+                The generator to generate the secrets and facts for this service.
+              '';
               type = lib.types.submodule (
                 { config, ... }:
                 {
@@ -151,6 +164,9 @@
               );
             };
             secret = lib.mkOption {
+              description = ''
+                Secret facts to generate for this service.
+              '';
               default = { };
               type = lib.types.attrsOf (
                 lib.types.submodule (secret: {
@@ -182,11 +198,11 @@
                     };
                 })
               );
-              description = ''
-                path where the secret is located in the filesystem
-              '';
             };
             public = lib.mkOption {
+              description = ''
+                Public facts to generate for this service.
+              '';
               default = { };
               type = lib.types.attrsOf (
                 lib.types.submodule (fact: {
@@ -208,6 +224,9 @@
                         config.clan.core.clanDir + "/machines/${config.clan.core.machineName}/facts/${fact.config.name}";
                     };
                     value = lib.mkOption {
+                      description = ''
+                        The value of the public fact.
+                      '';
                       defaultText = lib.literalExpression "\${config.clan.core.clanDir}/\${fact.config.path}";
                       type = lib.types.nullOr lib.types.str;
                       default =
@@ -231,15 +250,5 @@
 
     ./public/in_repo.nix
     ./public/vm.nix
-
-    # (lib.mkRenamedOptionModule
-    #   [
-    #     "clanCore"
-    #   ]
-    #   [
-    #     "clan"
-    #     "core"
-    #   ]
-    # )
   ];
 }

nixosModules/clanCore/state.nix

@@ -7,6 +7,9 @@
 {
   # interface
   options.clan.core.state = lib.mkOption {
+    description = ''
+      Define state directories to backup and restore
+    '';
     default = { };
     type = lib.types.attrsOf (
       lib.types.submodule (

nixosModules/clanCore/vars/settings.nix

@@ -64,6 +64,9 @@
     publicDirectory = lib.mkOption {
       type = lib.types.nullOr lib.types.path;
       default = null;
+      description = ''
+        The directory where public facts are stored.
+      '';
     };
   };
 }