WIP: nixos: mkEnableOption on steroids for discoverable man configuration.nix

lib/options.nix

@@ -15,6 +15,7 @@ rec {
     , defaultText ? null # Textual representation of the default, for in the manual.
     , example ? null # Example value used in the manual.
     , description ? null # String describing the option.
+    , packages ? [] # Related packages to be specified with `literalPackages*' functions
     , type ? null # Option type, providing type-checking and value merging.
     , apply ? null # Function that converts the option value to something else.
     , internal ? null # Whether the option is for NixOS developers only.
@@ -24,13 +25,56 @@ rec {
     } @ attrs:
     attrs // { _type = "option"; };
 
-  mkEnableOption = name: mkOption {
-    default = false;
-    example = true;
-    description = "Whether to enable ${name}.";
-    type = lib.types.bool;
+  # A boolean which determines whenever to do (or not to do) something.
+  mkWheneverToOption =
+    { default ? false
+    , what
+    , description ? null
+    , ...
+    } @ attrs:
+    mkOption ((removeAttrs attrs [ "what" ]) // {
+      inherit default;
+      example = !default;
+      type = lib.types.bool;
+      description = ''
+        Whether to ${what}.
+
+        ${optionalString (description != null) description}
+      '';
+    });
+
+  mkWheneverToPkgOption =
+    { description ? null
+    , broken ? false
+    , package ? null
+    , packages ? []
+    , ...
+    } @ attrs: let
+      pkgs = optional (package != null) package
+          ++ packages;
+    in
+    mkWheneverToOption (removeAttrs attrs [ "broken" "package" ] // {
+      description = ''
+        ${optionalString (description != null) description}
+
+        ${if broken then "THIS IS BROKEN."
+          else if (length pkgs > 1) then "Related packages:"
+          else if (length pkgs == 1) then "The package is:"
+          else ""}
+      '';
+      # Don't evaluate when marked as broken
+      packages = optional (!broken && package != null) package;
+    });
+
+  mkEnableOption = name: mkWheneverToPkgOption {
+    what = "enable ${name}";
   };
 
+  mkEnableOption' = { name ? null, ... } @ attrs:
+    mkWheneverToPkgOption (removeAttrs attrs [ "name" ] // {
+      what = "enable ${name}";
+    });
+
   # This option accept anything, but it does not produce any result.  This
   # is useful for sharing a module across different module sets without
   # having to implement similar features as long as the value of the options
@@ -77,6 +121,16 @@ rec {
   getValues = map (x: x.value);
   getFiles = map (x: x.file);
 
+  # Generate DocBook documentation for a list of packages
+  packageListToDocString = packages:
+    let
+      describePkg = n: p:
+          "<listitem>"
+        + "<para><option>${n}</option> (${p.name}): ${p.meta.description or "???"}.</para>"
+        # Lots of `longDescription's break DocBook, so we just wrap them into <programlisting>
+        + optionalString (p.meta ? longDescription) "\n<programlisting>${p.meta.longDescription}</programlisting>"
+        + "</listitem>";
+    in "<itemizedlist>${concatStringsSep "\n" (map ({name, value}: describePkg name value) packages)}</itemizedlist>";
 
   # Generate documentation template from the list of option declaration like
   # the set generated with filterOptionSets.
@@ -87,16 +141,17 @@ rec {
       let
         docOption = rec {
           name = showOption opt.loc;
-          description = opt.description or (throw "Option `${name}' has no description.");
+          description = (opt.description or (throw "Option `${name}' has no description."))
+                      + optionalString (opt ? packages && opt.packages != []) "\n\n${packageListToDocString opt.packages}";
           declarations = filter (x: x != unknownModule) opt.declarations;
           internal = opt.internal or false;
           visible = opt.visible or true;
           readOnly = opt.readOnly or false;
           type = opt.type.name or null;
         }
-        // (if opt ? example then { example = scrubOptionValue opt.example; } else {})
-        // (if opt ? default then { default = scrubOptionValue opt.default; } else {})
-        // (if opt ? defaultText then { default = opt.defaultText; } else {});
+        // (optionalAttrs (opt ? example)     { example = scrubOptionValue opt.example; })
+        // (optionalAttrs (opt ? default)     { default = scrubOptionValue opt.default; })
+        // (optionalAttrs (opt ? defaultText) { default = opt.defaultText; });
 
         subOptions =
           let ss = opt.type.getSubOptions opt.loc;
@@ -124,6 +179,14 @@ rec {
      functions. */
   literalExample = text: { _type = "literalExample"; inherit text; };
 
+  /* For use in the ‘packages’ option attribute. */
+  literalPackage' = pkgs: n: p: nameValuePair "${optionalString (n != "") (n + ".")}${p}" (getAttrFromPath (splitString "." p) pkgs);
+
+  literalPackages' = pkgs: n: l: map (literalPackage' pkgs n) l;
+
+  literalPackage = pkgs: n: literalPackage' { inherit pkgs; } "" n;
+
+  literalPackages = pkgs: l: literalPackages' { inherit pkgs; } "" l;
 
   /* Helper functions. */
   showOption = concatStringsSep ".";

nixos/doc/manual/default.nix

@@ -15,14 +15,6 @@ let
     else if builtins.isFunction x then "<function>"
     else x;
 
-  # Clean up declaration sites to not refer to the NixOS source tree.
-  optionsList' = flip map optionsList (opt: opt // {
-    declarations = map stripAnyPrefixes opt.declarations;
-  }
-  // optionalAttrs (opt ? example) { example = substFunction opt.example; }
-  // optionalAttrs (opt ? default) { default = substFunction opt.default; }
-  // optionalAttrs (opt ? type) { type = substFunction opt.type; });
-
   # We need to strip references to /nix/store/* from options,
   # including any `extraSources` if some modules came from elsewhere,
   # or else the build will fail.
@@ -32,8 +24,25 @@ let
   prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources);
   stripAnyPrefixes = flip (fold removePrefix) prefixesToStrip;
 
+  # Clean up declaration sites to not refer to the NixOS source tree.
+  optionsList' = flip map optionsList (opt: opt // {
+    declarations = map stripAnyPrefixes opt.declarations;
+  }
+  // optionalAttrs (opt ? example) { example = substFunction opt.example; }
+  // optionalAttrs (opt ? default) { default = substFunction opt.default; }
+  // optionalAttrs (opt ? type) { type = substFunction opt.type; });
+
+  # Custom "less" that pushes up all the things ending in ".enable*"
+  isEnable = x: hasPrefix "enable" (last (splitString "." x));
+  enableFirst = a: b: if       isEnable a && !isEnable b then true
+                      else if !isEnable a &&  isEnable b then false
+                      else a < b;
+
+  # Customly sort option list for the man page.
+  optionsList'' = sort (a: b: enableFirst a.name b.name) optionsList';
+
   # Convert the list of options into an XML file.
-  optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList');
+  optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList'');
 
   optionsDocBook = runCommand "options-db.xml" {} ''
     optionsXML=${optionsXML}

nixos/modules/hardware/ksm.nix

@@ -1,7 +1,9 @@
 { config, lib, ... }:
 
 {
-  options.hardware.enableKSM = lib.mkEnableOption "Kernel Same-Page Merging";
+  options.hardware.enableKSM = lib.mkEnableOption' {
+    name = "Kernel Same-Page Merging";
+  };
 
   config = lib.mkIf config.hardware.enableKSM {
     systemd.services.enable-ksm = {

nixos/modules/hardware/video/webcam/facetimehd.nix

@@ -12,7 +12,10 @@ in
 
 {
 
-  options.hardware.facetimehd.enable = mkEnableOption "facetimehd kernel module";
+  options.hardware.facetimehd.enable = mkEnableOption' {
+    name = "facetimehd kernel module";
+    package = literalPackage' kernelPackages "kernelPackages" "facetimehd";
+  };
 
   config = mkIf cfg.enable {
 

nixos/modules/programs/atop.nix

@@ -14,6 +14,11 @@ in
 
     programs.atop = {
 
+      enable = mkWheneverToPkgOption {
+        what = "globally configure atop";
+        package = literalPackage pkgs "pkgs.atop";
+      };
+
       settings = mkOption {
         type = types.attrs;
         default = {};
@@ -29,7 +34,7 @@ in
     };
   };
 
-  config = mkIf (cfg.settings != {}) {
+  config = mkIf cfg.enable {
     environment.etc."atoprc".text =
       concatStrings (mapAttrsToList (n: v: "${n} ${toString v}\n") cfg.settings);
   };

nixos/modules/programs/blcr.nix

@@ -1,27 +1,27 @@
 { config, lib, ... }:
 
+with lib;
+
 let
-  inherit (lib) mkOption mkIf;
   cfg = config.environment.blcr;
-  blcrPkg = config.boot.kernelPackages.blcr;
+  kp = config.boot.kernelPackages;
 in
 
 {
   ###### interface
 
   options = {
-    environment.blcr.enable = mkOption {
-      default = false;
-      description =
-        "Whether to enable support for the BLCR checkpointing tool.";
+    environment.blcr.enable = mkEnableOption' {
+      name = "support for the BLCR checkpointing tool";
+      #asserts #package = literalPackage' kp "kernelPackages" "blcr";
     };
   };
 
   ###### implementation
 
   config = mkIf cfg.enable {
     boot.kernelModules = [ "blcr" "blcr_imports" ];
-    boot.extraModulePackages = [ blcrPkg ];
-    environment.systemPackages = [ blcrPkg ];
+    boot.extraModulePackages = [ kp.blcr ];
+    environment.systemPackages = [ kp.blcr ];
   };
 }

nixos/modules/programs/cdemu.nix

@@ -7,13 +7,12 @@ in {
 
   options = {
     programs.cdemu = {
-      enable = mkOption {
-        default = false;
-        description = ''
-          <command>cdemu</command> for members of
-          <option>programs.cdemu.group</option>.
-        '';
+
+      enable = mkWheneverToPkgOption {
+        what = "globally configure cdemu";
+        package = literalPackage pkgs "pkgs.cdemu-daemon";
       };
+
       group = mkOption {
         default = "cdrom";
         description = ''

nixos/modules/programs/kbdlight.nix

@@ -7,7 +7,10 @@ let
 
 in
 {
-  options.programs.kbdlight.enable = mkEnableOption "kbdlight";
+  options.programs.kbdlight.enable = mkEnableOption' {
+    name = "kbdlight";
+    package = literalPackage pkgs "pkgs.kbdlight";
+  };
 
   config = mkIf cfg.enable {
     environment.systemPackages = [ pkgs.kbdlight ];

nixos/modules/programs/tmux.nix

@@ -1,7 +1,8 @@
 { config, pkgs, lib, ... }:
 
+with lib;
+
 let
-  inherit (lib) mkOption mkEnableOption mkIf mkMerge types;
 
   cfg = config.programs.tmux;
 
@@ -12,7 +13,10 @@ in
   options = {
     programs.tmux = {
 
-      enable = mkEnableOption "<command>tmux</command> - a <command>screen</command> replacement.";
+      enable = mkWheneverToPkgOption {
+        what = "globally configure tmux";
+        package = literalPackage pkgs "pkgs.tmux";
+      };
 
       tmuxconf = mkOption {
         default = "";

nixos/modules/services/audio/icecast.nix

@@ -44,7 +44,10 @@ in {
 
     services.icecast = {
 
-      enable = mkEnableOption "Icecast server";
+      enable = mkEnableOption' {
+        name = "Icecast server";
+        package = literalPackage pkgs "pkgs.icecast";
+      };
 
       hostname = mkOption {
         type = types.str;

nixos/modules/services/backup/rsnapshot.nix

@@ -7,7 +7,11 @@ in
 {
   options = {
     services.rsnapshot = {
-      enable = mkEnableOption "rsnapshot backups";
+
+      enable = mkWheneverToPkgOption {
+        what = "enable backups with rsnapshot";
+        package = literalPackage pkgs "pkgs.rsnapshot";
+      };
 
       extraConfig = mkOption {
         default = "";

nixos/modules/services/backup/znapzend.nix

@@ -8,7 +8,12 @@ in
 {
   options = {
     services.znapzend = {
-      enable = mkEnableOption "ZnapZend daemon";
+
+      enable = mkWheneverToPkgOption {
+        what = "enable backups with ZsnapZend";
+        package = literalPackage pkgs "pkgs.znapzend";
+      };
+
     };
   };
 

nixos/modules/services/databases/riak.nix

@@ -16,7 +16,11 @@ in
 
     services.riak = {
 
-      enable = mkEnableOption "riak";
+      enable = mkEnableOption' {
+        name = "riak";
+        broken = true;
+        package = literalPackage pkgs "pkgs.riak";
+      };
 
       package = mkOption {
         type = types.package;

nixos/modules/services/hardware/irqbalance.nix

@@ -9,7 +9,10 @@ let
 
 in
 {
-  options.services.irqbalance.enable = mkEnableOption "irqbalance daemon";
+  options.services.irqbalance.enable = mkEnableOption' {
+    name = "irqbalance daemon";
+    package = literalPackage pkgs "pkgs.irqbalance";
+  };
 
   config = mkIf cfg.enable {
 

nixos/modules/services/mail/dovecot.nix

@@ -70,7 +70,10 @@ in
 {
 
   options.services.dovecot2 = {
-    enable = mkEnableOption "Dovecot 2.x POP3/IMAP server";
+    enable = mkEnableOption' {
+      name = "Dovecot POP3/IMAP server";
+      package = literalPackage pkgs "pkgs.dovecot";
+    };
 
     enablePop3 = mkOption {
       type = types.bool;

nixos/modules/services/mail/postfix.nix

@@ -191,10 +191,9 @@ in
 
     services.postfix = {
 
-      enable = mkOption {
-        type = types.bool;
-        default = false;
-        description = "Whether to run the Postfix mail server.";
+      enable = mkEnableOption' {
+        name = "Postfix mail server";
+        package = literalPackage pkgs "pkgs.postfix";
       };
 
       enableSmtp = mkOption {