Add custom module documentation

boxes/colony.nix

@@ -1,4 +1,4 @@
-{ lib, pkgs, inputs, ... }:
+{ lib, pkgs, ... }:
 {
   fileSystems = {
     "/persist" = {

flake.nix

@@ -33,10 +33,9 @@
       ...
     }:
     let
-      inherit (builtins) mapAttrs;
-      inherit (lib) genAttrs mapAttrs';
-      inherit (lib.flake) defaultSystems eachDefaultSystem;
-      inherit (lib.my) addPrefix mkApp mkShellApp;
+      inherit (builtins) mapAttrs attrValues;
+      inherit (lib.flake) eachDefaultSystem;
+      inherit (lib.my) mkApp mkShellApp;
 
       extendLib = lib: lib.extend (final: prev: {
         my = import ./util.nix { lib = final; };
@@ -61,19 +60,8 @@
           ];
         })
         pkgsFlakes;
-    in
-    # Platform independent stuff
-    {
-      lib = lib.my;
 
-      nixosModules = mapAttrs
-        (_: path:
-          let path' = ./. + "/modules/${path}"; in
-          {
-            _file = path';
-            imports = [ (import path') ];
-          })
-        {
+      modules = mapAttrs (_: f: ./. + "/modules/${f}") {
         common = "common.nix";
         build = "build.nix";
         dynamic-motd = "dynamic-motd.nix";
@@ -81,8 +69,21 @@
         firewall = "firewall.nix";
         server = "server.nix";
       };
+    in
+    # Platform independent stuff
+    {
+      lib = lib.my;
+      nixpkgs = pkgs';
 
-      nixosConfigurations = import ./systems.nix { inherit lib pkgsFlakes inputs; modules = self.nixosModules; };
+      nixosModules = mapAttrs
+        (_: path:
+          {
+            _file = path;
+            imports = [ (import path) ];
+          })
+        modules;
+
+      nixosConfigurations = import ./systems.nix { inherit lib pkgsFlakes inputs; modules = attrValues modules; };
       systems = mapAttrs (_: system: system.config.system.build.toplevel) self.nixosConfigurations;
       vms = mapAttrs (_: system: system.config.my.build.devVM) self.nixosConfigurations;
     } //

modules/build.nix

@@ -1,7 +1,7 @@
 { lib, extendModules, modulesPath, baseModules, options, config, ... }:
 let
   inherit (lib) recursiveUpdate mkOption;
-  inherit (lib.my) mkBoolOpt;
+  inherit (lib.my) mkBoolOpt';
 
   cfg = config.my.build;
 
@@ -18,12 +18,13 @@ let
 in
 {
   options.my = with lib.types; {
-    boot.isDevVM = mkBoolOpt false;
+    boot.isDevVM = mkBoolOpt' false "Whether the system is a development VM.";
     build = options.system.build;
     asDevVM = mkOption {
       inherit (asDevVM) type;
       default = { };
       visible = "shallow";
+      description = "Configuration as a development VM";
     };
   };
 

modules/common.nix

@@ -1,11 +1,12 @@
 { lib, pkgs, inputs, system, config, options, ... }:
 let
   inherit (lib) mkIf mkDefault mkAliasDefinitions;
-  inherit (lib.my) mkOpt;
+  inherit (lib.my) mkOpt';
 in
 {
   options.my = with lib.types; {
-    user = mkOpt (attrsOf anything) { };
+    # Pretty hacky but too lazy to figure out if there's a better way to alias the options
+    user = mkOpt' (attrsOf anything) { } "User definition (as `users.users.*`).";
   };
 
   config =
@@ -40,13 +41,15 @@ in
       };
 
       nix = {
-        package = inputs.nix.defaultPackage.${system};
         extraOptions =
           ''
             experimental-features = nix-command flakes ca-derivations
           '';
       };
       nixpkgs = {
+        overlays = [
+          inputs.nix.overlay
+        ];
         config = {
           allowUnfree = true;
         };

modules/dynamic-motd.nix

@@ -1,7 +1,7 @@
 { lib, pkgs, config, ... }:
 let
   inherit (lib) optionalAttrs filterAttrs genAttrs mkIf mkDefault;
-  inherit (lib.my) mkOpt mkBoolOpt;
+  inherit (lib.my) mkOpt' mkBoolOpt';
 
   cfg = config.my.dynamic-motd;
 
@@ -9,9 +9,9 @@ let
 in
 {
   options.my.dynamic-motd = with lib.types; {
-    enable = mkBoolOpt true;
-    services = mkOpt (listOf str) [ "login" "ssh" ];
-    script = mkOpt (nullOr lines) null;
+    enable = mkBoolOpt' true "Whether to enable the dynamic message of the day PAM module.";
+    services = mkOpt' (listOf str) [ "login" "ssh" ] "PAM services to enable the dynamic message of the day module for.";
+    script = mkOpt' (nullOr lines) null "Script that generates message of the day.";
   };
 
   config = mkIf (cfg.enable && cfg.script != null) {

modules/firewall.nix

@@ -1,24 +1,24 @@
 { lib, options, config, ... }:
 let
   inherit (lib) optionalString concatStringsSep concatMapStringsSep optionalAttrs mkIf mkDefault mkMerge mkOverride;
-  inherit (lib.my) parseIPPort mkOpt mkBoolOpt dummyOption;
+  inherit (lib.my) parseIPPort mkOpt' mkBoolOpt' dummyOption;
 
   cfg = config.my.firewall;
 in
 {
   options.my.firewall = with lib.types; {
-    enable = mkBoolOpt true;
+    enable = mkBoolOpt' true "Whether to enable the nftables-based firewall.";
     trustedInterfaces = options.networking.firewall.trustedInterfaces;
     tcp = {
-      allowed = mkOpt (listOf (either port str)) [ "ssh" ];
+      allowed = mkOpt' (listOf (either port str)) [ "ssh" ] "TCP ports to open.";
     };
     udp = {
-      allowed = mkOpt (listOf (either port str)) [ ];
+      allowed = mkOpt' (listOf (either port str)) [ ] "UDP ports to open.";
     };
-    extraRules = mkOpt lines "";
+    extraRules = mkOpt' lines "" "Arbitrary additional nftables rules.";
 
     nat = with options.networking.nat; {
-      enable = mkBoolOpt true;
+      enable = mkBoolOpt' true "Whether to enable IP forwarding and NAT.";
       inherit externalInterface forwardPorts;
     };
   };

modules/server.nix

@@ -1,11 +1,13 @@
 { config, lib, ... }:
 let
   inherit (lib) mkIf;
-  inherit (lib.my) mkBoolOpt;
+  inherit (lib.my) mkBoolOpt';
+
+  cfg = config.my.server;
 in
 {
-  options.my.server.enable = mkBoolOpt false;
-  config = mkIf config.my.server.enable {
+  options.my.server.enable = mkBoolOpt' false "Whether to enable common configuration for servers.";
+  config = mkIf cfg.enable {
     services.getty.autologinUser = config.my.user.name;
   };
 }

modules/tmproot.nix

@@ -1,8 +1,7 @@
-{ lib, pkgs, inputs, config, ... }:
+{ lib, pkgs, config, ... }:
 let
-  inherit (builtins) elem;
-  inherit (lib) concatStringsSep concatMap concatMapStringsSep mkIf mkDefault mkMerge mkForce mkVMOverride;
-  inherit (lib.my) mkOpt mkBoolOpt mkVMOverride' dummyOption;
+  inherit (lib) concatStringsSep concatMap concatMapStringsSep mkIf mkDefault mkMerge mkVMOverride;
+  inherit (lib.my) mkOpt' mkBoolOpt' mkVMOverride' dummyOption;
 
   cfg = config.my.tmproot;
 
@@ -54,16 +53,14 @@ let
   };
 in
 {
-  imports = [ inputs.impermanence.nixosModule ];
-
   options = with lib.types; {
     my.tmproot = {
-      enable = mkBoolOpt true;
-      persistDir = mkOpt str "/persist";
-      size = mkOpt str "2G";
+      enable = mkBoolOpt' true "Whether to enable tmproot.";
+      persistDir = mkOpt' str "/persist" "Path where persisted files are stored.";
+      size = mkOpt' str "2G" "Size of tmpfs root";
       unsaved = {
-        showMotd = mkBoolOpt true;
-        ignore = mkOpt (listOf str) [ ];
+        showMotd = mkBoolOpt' true "Whether to show unsaved files with `dynamic-motd`.";
+        ignore = mkOpt' (listOf str) [ ] "Path prefixes to ignore if unsaved.";
       };
     };
 

systems.nix

@@ -25,9 +25,16 @@ let
     in
     nixosSystem' {
       inherit lib system;
-      specialArgs = { inherit inputs system; };
-      modules = attrValues modules ++ [
+      baseModules =
+        (import "${pkgsFlake}/nixos/modules/module-list.nix") ++ [
+          # Importing modules from module args causes infinite recursion
+          inputs.impermanence.nixosModule
+          inputs.agenix.nixosModules.age
+          inputs.home-manager.nixosModule
+        ] ++ modules;
+      modules = [
         {
+          _module.args = { inherit system inputs; };
           system.name = name;
           networking.hostName = mkDefault name;
         }

util.nix

@@ -26,11 +26,18 @@ rec {
   mkShellApp = pkgs: name: text: mkApp (pkgs.writeShellScript name text).outPath;
 
   mkOpt = type: default: mkOption { inherit type default; };
+  mkOpt' = type: default: description: mkOption { inherit type default description; };
   mkBoolOpt = default: mkOption {
     inherit default;
     type = types.bool;
     example = true;
   };
-  mkVMOverride' = mkOverride 9;
+  mkBoolOpt' = default: description: mkOption {
+    inherit default description;
+    type = types.bool;
+    example = true;
+  };
   dummyOption = mkOption { };
+
+  mkVMOverride' = mkOverride 9;
 }