Merge pull request #15025 from ericsagnes/modules/manual

manual: automatically generate modules documentation

lib/modules.nix

@@ -105,8 +105,12 @@ rec {
   /* Massage a module into canonical form, that is, a set consisting
      of ‘options’, ‘config’ and ‘imports’ attributes. */
   unifyModuleSyntax = file: key: m:
+    let metaSet = if m ? meta 
+      then { meta = m.meta; }
+      else {};
+    in
     if m ? config || m ? options then
-      let badAttrs = removeAttrs m ["imports" "options" "config" "key" "_file"]; in
+      let badAttrs = removeAttrs m ["imports" "options" "config" "key" "_file" "meta"]; in
       if badAttrs != {} then
         throw "Module `${key}' has an unsupported attribute `${head (attrNames badAttrs)}'. This is caused by assignments to the top-level attributes `config' or `options'."
       else
@@ -114,14 +118,14 @@ rec {
           key = toString m.key or key;
           imports = m.imports or [];
           options = m.options or {};
-          config = m.config or {};
+          config = mkMerge [ (m.config or {}) metaSet ];
         }
     else
       { file = m._file or file;
         key = toString m.key or key;
         imports = m.require or [] ++ m.imports or [];
         options = {};
-        config = removeAttrs m ["key" "_file" "require" "imports"];
+        config = mkMerge [ (removeAttrs m ["key" "_file" "require" "imports"]) metaSet ];
       };
 
   applyIfFunction = key: f: args@{ config, options, lib, ... }: if isFunction f then

nixos/doc/manual/configuration/configuration.xml

@@ -25,14 +25,10 @@ effect after you run <command>nixos-rebuild</command>.</para>
 <xi:include href="linux-kernel.xml" />
 <xi:include href="grsecurity.xml" />
 
-<!-- FIXME: auto-include NixOS module docs -->
-<xi:include href="postgresql.xml" />
-<xi:include href="gitlab.xml" />
-<xi:include href="taskserver.xml" />
-<xi:include href="acme.xml" />
-<xi:include href="input-methods.xml" />
 <xi:include href="emacs.xml" />
+<xi:include href="modules.xml" xpointer="xpointer(//section[@id='modules']/*)" />
 
 <!-- Apache; libvirtd virtualisation -->
 
 </part>
+

nixos/doc/manual/default.nix

@@ -1,4 +1,4 @@
-{ pkgs, options, version, revision, extraSources ? [] }:
+{ pkgs, options, config, version, revision, extraSources ? [] }:
 
 with pkgs;
 
@@ -51,6 +51,14 @@ let
 
   sources = lib.sourceFilesBySuffices ./. [".xml"];
 
+  modulesDoc = builtins.toFile "modules.xml" ''
+    <section xmlns:xi="http://www.w3.org/2001/XInclude" id="modules">
+    ${(lib.concatMapStrings (path: ''
+      <xi:include href="${path}" />
+    '') (lib.catAttrs "value" config.meta.doc))}
+    </section>
+  '';
+
   copySources =
     ''
       cp -prd $sources/* . # */
@@ -61,6 +69,7 @@ let
       cp ${../../modules/security/acme.xml} configuration/acme.xml
       cp ${../../modules/i18n/input-method/default.xml} configuration/input-methods.xml
       cp ${../../modules/services/editors/emacs.xml} configuration/emacs.xml
+      ln -s ${modulesDoc} configuration/modules.xml
       ln -s ${optionsDocBook} options-db.xml
       echo "${version}" > version
     '';

nixos/modules/i18n/input-method/default.nix

@@ -62,4 +62,9 @@ in
     environment.systemPackages = [ cfg.package gtk2_cache gtk3_cache ];
   };
 
+  meta = {
+    maintainers = with lib.maintainers; [ ericsagnes ];
+    doc = ./default.xml;
+  };
+
 }

nixos/modules/misc/meta.nix

@@ -39,7 +39,7 @@ in
         default = [];
         example = [ lib.maintainers.all ];
         description = ''
-	  List of maintainers of each module.  This option should be defined at
+          List of maintainers of each module.  This option should be defined at
           most once per module.
         '';
       };
@@ -49,7 +49,7 @@ in
         internal = true;
         example = "./meta.xml";
         description = ''
-	  Documentation prologe for the set of options of each module.  This
+          Documentation prologe for the set of options of each module.  This
           option should be defined at most once per module.
         '';
       };
@@ -57,7 +57,5 @@ in
     };
   };
 
-  config = {
-    meta.maintainers = singleton lib.maintainers.pierron;
-  };
+  meta.maintainers = singleton lib.maintainers.pierron;
 }

nixos/modules/security/acme.nix

@@ -290,9 +290,10 @@ in
       systemd.targets."acme-certificates" = {};
     })
 
-    { meta.maintainers = with lib.maintainers; [ abbradar fpletz globin ];
-      meta.doc = ./acme.xml;
-    }
   ];
 
+  meta = {
+    maintainers = with lib.maintainers; [ abbradar fpletz globin ];
+    doc = ./acme.xml;
+  };
 }

nixos/modules/services/databases/postgresql.nix

@@ -253,4 +253,6 @@ in
 
   };
 
+  meta.doc = ./postgresql.xml;
+
 }

nixos/modules/services/misc/gitlab.nix

@@ -556,4 +556,7 @@ in {
     };
 
   };
+
+  meta.doc = ./gitlab.xml;
+
 }

nixos/modules/services/misc/nixos-manual.nix

@@ -17,7 +17,7 @@ let
     Caveat: even if the package is reached by a different means,
     the path above will be shown and not e.g. `${config.services.foo.package}`. */
   manual = import ../../../doc/manual {
-    inherit pkgs;
+    inherit pkgs config;
     version = config.system.nixosRelease;
     revision = "release-${config.system.nixosRelease}";
     options =

nixos/modules/services/misc/taskserver/default.nix

@@ -534,6 +534,7 @@ in {
     (mkIf (cfg.enable && cfg.listenHost != "localhost") {
       networking.firewall.allowedTCPPorts = [ cfg.listenPort ];
     })
-    { meta.doc = ./taskserver.xml; }
   ];
+
+  meta.doc = ./doc.xml;
 }

nixos/modules/services/networking/teamspeak3.nix

@@ -95,47 +95,44 @@ in
 
   ###### implementation
 
-  config = mkMerge [
-    (mkIf cfg.enable {
-      users.users.teamspeak = {
-        description = "Teamspeak3 voice communication server daemon";
-        group = group;
-        uid = config.ids.uids.teamspeak;
-        home = cfg.dataDir;
-        createHome = true;
-      };
-
-      users.groups.teamspeak = {
-        gid = config.ids.gids.teamspeak;
-      };
+  config = mkIf cfg.enable {
+    users.users.teamspeak = {
+      description = "Teamspeak3 voice communication server daemon";
+      group = group;
+      uid = config.ids.uids.teamspeak;
+      home = cfg.dataDir;
+      createHome = true;
+    };
 
-      systemd.services.teamspeak3-server = {
-        description = "Teamspeak3 voice communication server daemon";
-        after = [ "network.target" ];
-        wantedBy = [ "multi-user.target" ];
+    users.groups.teamspeak = {
+      gid = config.ids.gids.teamspeak;
+    };
 
-        preStart = ''
-          mkdir -p ${cfg.logPath}
-          chown ${user}:${group} ${cfg.logPath}
+    systemd.services.teamspeak3-server = {
+      description = "Teamspeak3 voice communication server daemon";
+      after = [ "network.target" ];
+      wantedBy = [ "multi-user.target" ];
+
+      preStart = ''
+        mkdir -p ${cfg.logPath}
+        chown ${user}:${group} ${cfg.logPath}
+      '';
+
+      serviceConfig = {
+        ExecStart = ''
+          ${ts3}/bin/ts3server \
+            dbsqlpath=${ts3}/lib/teamspeak/sql/ logpath=${cfg.logPath} \
+            voice_ip=${cfg.voiceIP} default_voice_port=${toString cfg.defaultVoicePort} \
+            filetransfer_ip=${cfg.fileTransferIP} filetransfer_port=${toString cfg.fileTransferPort} \
+            query_ip=${cfg.queryIP} query_port=${toString cfg.queryPort}
         '';
-
-        serviceConfig = {
-          ExecStart = ''
-            ${ts3}/bin/ts3server \
-              dbsqlpath=${ts3}/lib/teamspeak/sql/ logpath=${cfg.logPath} \
-              voice_ip=${cfg.voiceIP} default_voice_port=${toString cfg.defaultVoicePort} \
-              filetransfer_ip=${cfg.fileTransferIP} filetransfer_port=${toString cfg.fileTransferPort} \
-              query_ip=${cfg.queryIP} query_port=${toString cfg.queryPort}
-          '';
-          WorkingDirectory = cfg.dataDir;
-          User = user;
-          Group = group;
-          PermissionsStartOnly = true;
-        };
+        WorkingDirectory = cfg.dataDir;
+        User = user;
+        Group = group;
+        PermissionsStartOnly = true;
       };
-    })
-    {
-      meta.maintainers = with lib.maintainers; [ arobyn ];
-    }
-  ];
+    };
+  };
+
+  meta.maintainers = with lib.maintainers; [ arobyn ];
 }

nixos/modules/services/networking/wpa_supplicant.nix

@@ -111,57 +111,54 @@ in {
     };
   };
 
-  config = mkMerge [
-    (mkIf cfg.enable {
-      assertions = flip mapAttrsToList cfg.networks (name: cfg: {
-        assertion = cfg.psk == null || cfg.pskRaw == null;
-        message = ''networking.wireless."${name}".psk and networking.wireless."${name}".pskRaw are mutually exclusive'';
-      });
-
-      environment.systemPackages =  [ pkgs.wpa_supplicant ];
-
-      services.dbus.packages = [ pkgs.wpa_supplicant ];
-
-      # FIXME: start a separate wpa_supplicant instance per interface.
-      systemd.services.wpa_supplicant = let
-        ifaces = cfg.interfaces;
-        deviceUnit = interface: [ "sys-subsystem-net-devices-${interface}.device" ];
-      in {
-        description = "WPA Supplicant";
-
-        after = [ "network-interfaces.target" ] ++ lib.concatMap deviceUnit ifaces;
-        requires = lib.concatMap deviceUnit ifaces;
-        wantedBy = [ "network.target" ];
-
-        path = [ pkgs.wpa_supplicant ];
-
-        script = ''
-          ${if ifaces == [] then ''
-            for i in $(cd /sys/class/net && echo *); do
-              DEVTYPE=
-              source /sys/class/net/$i/uevent
-              if [ "$DEVTYPE" = "wlan" -o -e /sys/class/net/$i/wireless ]; then
-                ifaces="$ifaces''${ifaces:+ -N} -i$i"
-              fi
-            done
-          '' else ''
-            ifaces="${concatStringsSep " -N " (map (i: "-i${i}") ifaces)}"
-          ''}
-          exec wpa_supplicant -s -u -D${cfg.driver} -c ${configFile} $ifaces
-        '';
-      };
-
-      powerManagement.resumeCommands = ''
-        ${config.systemd.package}/bin/systemctl try-restart wpa_supplicant
+  config = mkIf cfg.enable {
+    assertions = flip mapAttrsToList cfg.networks (name: cfg: {
+      assertion = cfg.psk == null || cfg.pskRaw == null;
+      message = ''networking.wireless."${name}".psk and networking.wireless."${name}".pskRaw are mutually exclusive'';
+    });
+
+    environment.systemPackages =  [ pkgs.wpa_supplicant ];
+
+    services.dbus.packages = [ pkgs.wpa_supplicant ];
+
+    # FIXME: start a separate wpa_supplicant instance per interface.
+    systemd.services.wpa_supplicant = let
+      ifaces = cfg.interfaces;
+      deviceUnit = interface: [ "sys-subsystem-net-devices-${interface}.device" ];
+    in {
+      description = "WPA Supplicant";
+
+      after = [ "network-interfaces.target" ] ++ lib.concatMap deviceUnit ifaces;
+      requires = lib.concatMap deviceUnit ifaces;
+      wantedBy = [ "network.target" ];
+
+      path = [ pkgs.wpa_supplicant ];
+
+      script = ''
+        ${if ifaces == [] then ''
+          for i in $(cd /sys/class/net && echo *); do
+            DEVTYPE=
+            source /sys/class/net/$i/uevent
+            if [ "$DEVTYPE" = "wlan" -o -e /sys/class/net/$i/wireless ]; then
+              ifaces="$ifaces''${ifaces:+ -N} -i$i"
+            fi
+          done
+        '' else ''
+          ifaces="${concatStringsSep " -N " (map (i: "-i${i}") ifaces)}"
+        ''}
+        exec wpa_supplicant -s -u -D${cfg.driver} -c ${configFile} $ifaces
       '';
+    };
 
-      # Restart wpa_supplicant when a wlan device appears or disappears.
-      services.udev.extraRules = ''
-        ACTION=="add|remove", SUBSYSTEM=="net", ENV{DEVTYPE}=="wlan", RUN+="${config.systemd.package}/bin/systemctl try-restart wpa_supplicant.service"
-      '';
-    })
-    {
-      meta.maintainers = with lib.maintainers; [ globin ];
-    }
-  ];
+    powerManagement.resumeCommands = ''
+      ${config.systemd.package}/bin/systemctl try-restart wpa_supplicant
+    '';
+
+    # Restart wpa_supplicant when a wlan device appears or disappears.
+    services.udev.extraRules = ''
+      ACTION=="add|remove", SUBSYSTEM=="net", ENV{DEVTYPE}=="wlan", RUN+="${config.systemd.package}/bin/systemctl try-restart wpa_supplicant.service"
+    '';
+  };
+
+  meta.maintainers = with lib.maintainers; [ globin ];
 }