ship extended manpages (esp for man configuration.nix)

hosts/common/default.nix

@@ -60,4 +60,11 @@
   # link debug symbols into /run/current-system/sw/lib/debug
   # hopefully picked up by gdb automatically?
   environment.enableDebugInfo = true;
+
+  # enable manpages targeted at developers (i.e. `devman` package outputs)
+  # <https://search.nixos.org/options?channel=unstable&show=documentation.dev.enable&query=documentation.dev>
+  documentation.dev.enable = true;
+  # document my own, custom (non-nixpkgs) options in `man configuration.nix`:
+  documentation.nixos.includeAllModules = true;
+  documentation.nixos.options.warningsAreErrors = false;  #< TODO: fix all my options to have `description`, then enable.
 }

hosts/common/fs/remote-home.nix

@@ -1,7 +1,7 @@
 { config, lib, ... }:
 let
   fsOpts = import ./fs-opts.nix;
-  ifSshAuthorized = lib.mkIf (((config.sane.hosts.by-name."${config.networking.hostName}" or {}).ssh or {}).authorized or false);
+  ifSshAuthorized = lib.mkIf (((config.sane.hosts.by-name."${config.networking.hostName or ""}" or {}).ssh or {}).authorized or false);
 
   remoteHome = name: { host ? name }: let
     mountpoint = "/mnt/${name}/home";

hosts/common/programs/assorted.nix

@@ -17,7 +17,7 @@ in
       enableFor.system = lib.mkDefault true;
       packageUnwrapped = null;
       suggestedPrograms = [ "nixosBuiltinsNet" ]
-        ++ lib.optionals config.networking.wireless.enable [ "nixosBuiltinsWireless" ];
+        ++ lib.optionals ((config.networking.wireless or {}).enable or false) [ "nixosBuiltinsWireless" ];
     };
     nixosBuiltinsNet = declPackageSet [
       # from nixos/modules/tasks/network-interfaces.nix

hosts/modules/wg-home.nix

@@ -34,6 +34,7 @@ in
     sane.services.wg-home.ip = mkOption {
       type = types.str;
       default = config.sane.hosts.by-name."${config.networking.hostName}".wg-home.ip;
+      defaultText = lib.literalExpression ''config.sane.hosts.by-name."''${config.networking.hostName}".wg-home.ip'';
     };
   };
 

modules/ports.nix

@@ -19,11 +19,12 @@ let
       };
       description = mkOption {
         type = types.str;
-        default = "colin-${config.net.hostName}";
         description = ''
           short description of why this port is open.
           this is shown, for example, in an upstream's UPnP status page.
         '';
+        default = "colin-${config.net.hostName}";
+        defaultText = lib.literalExpression ''"colin-''${config.net.hostName}"'';
       };
     };
   };

modules/programs/default.nix

@@ -131,6 +131,7 @@ let
       name = mkOption {
         type = types.str;
         default = name;
+        defaultText = lib.literalExpression "name";
       };
       packageUnwrapped = mkOption {
         type = types.nullOr types.package;
@@ -146,6 +147,7 @@ let
             # this indexing will throw if the package doesn't exist and the user forgets to specify
             # a valid source explicitly.
             lib.getAttrFromPath pkgPath pkgs;
+        defaultText = lib.literalExpression ''pkgs.''${lib.splitString "." name}'';
       };
       package = mkOption {
         type = types.nullOr types.package;
@@ -156,14 +158,12 @@ let
       };
       enableFor.system = mkOption {
         type = types.bool;
-        default = defaultEnables."${name}".system;
         description = ''
           place this program on the system PATH
         '';
       };
       enableFor.user = mkOption {
         type = types.attrsOf types.bool;
-        default = defaultEnables."${name}".user;
         description = ''
           place this program on the PATH for some specified user(s).
         '';
@@ -647,7 +647,7 @@ let
       };
       sandbox.extraRuntimePaths = mkOption {
         type = types.listOf types.str;
-        default = [ ];
+        default = [];
         description = ''
           additional $XDG_RUNTIME_DIR-relative paths to bind into the sandbox.
           e.g. `[ "bus" "wayland-1" ]` to bind the dbus and wayland sockets.
@@ -716,7 +716,10 @@ let
     config = let
       enabledForUser = builtins.any (en: en) (lib.attrValues config.enableFor.user);
       passesSlowTest = config.buildCost <= saneCfg.maxBuildCost;
+      mkWeakDefault = lib.mkOverride 2000; #< even weaker than `mkDefault`
     in {
+      enableFor.system = mkWeakDefault defaultEnables."${name}".system;
+      enableFor.user = mkWeakDefault defaultEnables."${name}".user;
       enabled = (config.enableFor.system || enabledForUser) && passesSlowTest;
       package = if config.packageUnwrapped == null then
         null

modules/services/clightning.nix

@@ -46,28 +46,28 @@ in
       user = mkOption {
         type = types.str;
         default = "clightning";
-        description = mdDoc "The user as which to run clightning.";
+        description = "The user as which to run clightning.";
       };
       group = mkOption {
         type = types.str;
         default = cfg.user;
-        description = mdDoc "The group as which to run clightning.";
+        description = "The group as which to run clightning.";
       };
       dataDir = mkOption {
         type = types.path;
         default = "/var/lib/clightning";
-        description = mdDoc "The data directory for clightning.";
+        description = "The data directory for clightning.";
       };
       networkDir = mkOption {
         type = types.path;
         default = "${cfg.dataDir}/bitcoin";
-        description = mdDoc "The network data directory.";
+        description = "The network data directory.";
       };
 
       address = mkOption {
         type = types.str;
         default = "127.0.0.1";
-        description = mdDoc "Address to listen for peer connections.";
+        description = "Address to listen for peer connections.";
       };
       publicAddress = mkOption {
         type = types.nullOr types.str;
@@ -85,7 +85,7 @@ in
       getPublicAddressCmd = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = mdDoc ''
+        description = ''
           Bash expression which outputs the public service address to announce to peers.
           this is an alternative to the `publicAddress` option, for if the address is not known statically (e.g. tor).
         '';
@@ -94,19 +94,19 @@ in
       port = mkOption {
         type = types.port;
         default = 9735;
-        description = mdDoc "Port to listen for peer connections.";
+        description = "Port to listen for peer connections.";
       };
       proxy = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = mdDoc ''
+        description = ''
           Socks proxy for connecting to Tor nodes (or for all connections if option always-use-proxy is set).
         '';
       };
       always-use-proxy = mkOption {
         type = types.bool;
         default = cfg.proxy != null;
-        description = mdDoc ''
+        description = ''
           Always use the proxy, even to connect to normal IP addresses.
           You can still connect to Unix domain sockets manually.
           This also disables all DNS lookups, to avoid leaking address information.
@@ -119,7 +119,7 @@ in
         example = ''
           alias=mynode
         '';
-        description = mdDoc ''
+        description = ''
           Extra lines appended to the configuration file.
 
           See all available options at

modules/services/dyn-dns.nix

@@ -32,6 +32,7 @@ in
 
       ipCmd = mkOption {
         default = getIp;
+        defaultText = "path/to/sane-ip-check --json";
         type = types.path;
         description = "command to run to query the current WAN IP";
       };

modules/services/kiwix-serve.nix

@@ -12,18 +12,18 @@ in
       port = mkOption {
         type = types.port;
         default = 80;
-        description = lib.mdDoc "Port number to listen on.";
+        description = "Port number to listen on.";
       };
       listenAddress = mkOption {
         type = types.nullOr types.str;
         default = null;
-        description = lib.mdDoc ''
+        description = ''
           IP address to listen on. Listens on all available addresses if unspecified.
         '';
       };
       zimPaths = mkOption {
         type = types.nonEmptyListOf (types.either types.str types.path);
-        description = lib.mdDoc "ZIM file path(s)";
+        description = "ZIM file path(s)";
       };
     };
   };