From 8906aa28e4de1f1b53a99691c1373292f1106766 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Na=C3=AFm=20Favier?= <n@monade.li>
Date: Sun, 11 Dec 2022 15:56:09 +0100
Subject: [PATCH] doc/lib-functions: remove warnings

Building the nixpkgs manual currently triggers a bunch of deprecation
warnings, because every attribute in `lib` is evaluated to see if it's
an attrset to generate locations for.

Instead, share the lib subsets to include in the documentation
between `lib-function-docs` and `lib-function-locations` so they can
coordinate.

Also generate the list of sections instead of duplicating it in
`library.xml`.
---
 doc/doc-support/default.nix                | 16 ++++++++--
 doc/doc-support/lib-function-docs.nix      | 35 +++++++++++-----------
 doc/doc-support/lib-function-locations.nix |  6 ++--
 doc/doc-support/parameters.xml             |  1 +
 doc/functions/library.xml                  | 24 ++-------------
 5 files changed, 38 insertions(+), 44 deletions(-)

diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix
index 429c7a5fbe80..0b188c700010 100644
--- a/doc/doc-support/default.nix
+++ b/doc/doc-support/default.nix
@@ -3,8 +3,20 @@ let
   inherit (pkgs) lib;
   inherit (lib) hasPrefix removePrefix;
 
-  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
-  functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; };
+  libsets = {
+    asserts = "Assert functions";
+    attrsets = "Attribute-set functions";
+    strings = "String manipulation functions";
+    trivial = "Miscellaneous functions";
+    lists = "List manipulation functions";
+    debug = "Debugging functions";
+    options = "NixOS / nixpkgs option handling";
+    filesystem = "Filesystem functions";
+    sources = "Source filtering functions";
+  };
+
+  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; };
+  functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs libsets; };
   version = pkgs.lib.version;
 
   epub-xsl = pkgs.writeText "epub.xsl" ''
diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix
index 4e67609e23fb..a11de1a9f6f1 100644
--- a/doc/doc-support/lib-function-docs.nix
+++ b/doc/doc-support/lib-function-docs.nix
@@ -1,30 +1,31 @@
-# Generates the documentation for library functions via nixdoc. To add
-# another library function file to this list, the include list in the
-# file `doc/functions/library.xml` must also be updated.
+# Generates the documentation for library functions via nixdoc.
 
-{ pkgs ? import ./.. {}, locationsXml }:
+{ pkgs, locationsXml, libsets }:
 
 with pkgs; stdenv.mkDerivation {
   name = "nixpkgs-lib-docs";
-  src = ./../../lib;
+  src = ../../lib;
 
   buildInputs = [ nixdoc ];
   installPhase = ''
     function docgen {
-      nixdoc -c "$1" -d "$2" -f "../lib/$1.nix"  > "$out/$1.xml"
+      nixdoc -c "$1" -d "$2" -f "$1.nix" > "$out/$1.xml"
+      echo "<xi:include href='$1.xml' />" >> "$out/index.xml"
     }
 
-    mkdir -p $out
-    ln -s ${locationsXml} $out/locations.xml
+    mkdir -p "$out"
 
-    docgen asserts 'Assert functions'
-    docgen attrsets 'Attribute-set functions'
-    docgen strings 'String manipulation functions'
-    docgen trivial 'Miscellaneous functions'
-    docgen lists 'List manipulation functions'
-    docgen debug 'Debugging functions'
-    docgen options 'NixOS / nixpkgs option handling'
-    docgen filesystem 'Filesystem functions'
-    docgen sources 'Source filtering functions'
+    cat > "$out/index.xml" << 'EOF'
+    <?xml version="1.0" encoding="utf-8"?>
+    <root xmlns:xi="http://www.w3.org/2001/XInclude">
+    EOF
+
+    ${lib.concatStrings (lib.mapAttrsToList (name: description: ''
+      docgen ${name} ${lib.escapeShellArg description}
+    '') libsets)}
+
+    echo "</root>" >> "$out/index.xml"
+
+    ln -s ${locationsXml} $out/locations.xml
   '';
 }
diff --git a/doc/doc-support/lib-function-locations.nix b/doc/doc-support/lib-function-locations.nix
index 68edd2709854..7db176256e0a 100644
--- a/doc/doc-support/lib-function-locations.nix
+++ b/doc/doc-support/lib-function-locations.nix
@@ -1,4 +1,4 @@
-{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
+{ pkgs, nixpkgs ? { }, libsets }:
 let
   revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master");
 
@@ -16,9 +16,7 @@ let
         subsetname = subsetname;
         functions = libDefPos toplib.${subsetname};
       })
-      (builtins.filter
-        (name: builtins.isAttrs toplib.${name})
-        (builtins.attrNames toplib));
+      (builtins.attrNames libsets);
 
   nixpkgsLib = pkgs.lib;
 
diff --git a/doc/doc-support/parameters.xml b/doc/doc-support/parameters.xml
index 50ff25fe1075..5b39d2f7f1a5 100644
--- a/doc/doc-support/parameters.xml
+++ b/doc/doc-support/parameters.xml
@@ -11,6 +11,7 @@
  <xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" />
  <xsl:param name="xref.with.number.and.title" select="0" />
  <xsl:param name="use.id.as.filename" select="1" />
+ <xsl:param name="generate.section.toc.level" select="1" />
  <xsl:param name="toc.section.depth" select="0" />
  <xsl:param name="admon.style" select="''" />
  <xsl:param name="callout.graphics.extension" select="'.svg'" />
diff --git a/doc/functions/library.xml b/doc/functions/library.xml
index 0a8bae229f26..788ea0b94f1f 100644
--- a/doc/functions/library.xml
+++ b/doc/functions/library.xml
@@ -8,25 +8,7 @@
   Nixpkgs provides a standard library at <varname>pkgs.lib</varname>, or through <code>import &lt;nixpkgs/lib&gt;</code>.
  </para>
 
-<!-- These docs are generated via nixdoc. To add another generated
-      library function file to this list, the file
-      `lib-function-docs.nix` must also be updated. -->
-
- <xi:include href="./library/generated/asserts.xml" />
-
- <xi:include href="./library/generated/attrsets.xml" />
-
- <xi:include href="./library/generated/strings.xml" />
-
- <xi:include href="./library/generated/trivial.xml" />
-
- <xi:include href="./library/generated/lists.xml" />
-
- <xi:include href="./library/generated/debug.xml" />
-
- <xi:include href="./library/generated/options.xml" />
-
- <xi:include href="./library/generated/filesystem.xml" />
-
- <xi:include href="./library/generated/sources.xml" />
+ <!-- The index must have a root element to declare namespaces, but we
+      don't want to include it, so we select all of its children. -->
+ <xi:include href="./library/generated/index.xml" xpointer="xpointer(/root/*)" />
 </section>