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

@@ -57,7 +57,5 @@ in
     };
   };
 
-  config = {
   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,8 +95,7 @@ in
 
   ###### implementation
 
-  config = mkMerge [
-    (mkIf cfg.enable {
+  config = mkIf cfg.enable {
     users.users.teamspeak = {
       description = "Teamspeak3 voice communication server daemon";
       group = group;
@@ -133,9 +132,7 @@ in
         PermissionsStartOnly = true;
       };
     };
-    })
-    {
+  };
+
   meta.maintainers = with lib.maintainers; [ arobyn ];
 }
-  ];
-}

nixos/modules/services/networking/wpa_supplicant.nix

@@ -111,8 +111,7 @@ in {
     };
   };
 
-  config = mkMerge [
-    (mkIf cfg.enable {
+  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'';
@@ -159,9 +158,7 @@ in {
     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 ];
 }
-  ];
-}