Generate links to function definitions

Hydra passes the full revision in to the input, which we pass through.

If we don't get this ,we try to get it from other sources, or default to
master which should have the definition in a close-ish location.

All published docs should have theURL resolve properly, only local
hackers will have the link break.

doc/.gitignore

@@ -4,3 +4,4 @@
 out
 manual-full.xml
 highlightjs
+functions/library/locations.xml

doc/Makefile

@@ -19,7 +19,7 @@ fix-misc-xml:
 
 .PHONY: clean
 clean:
-	rm -f ${MD_TARGETS} .version manual-full.xml
+	rm -f ${MD_TARGETS} .version manual-full.xml functions/library/locations.xml
 	rm -rf ./out/ ./highlightjs
 
 .PHONY: validate
@@ -69,13 +69,17 @@ highlightjs:
 	cp -r "$$HIGHLIGHTJS/loader.js" highlightjs/
 
 
-manual-full.xml: ${MD_TARGETS} .version *.xml **/*.xml **/**/*.xml
+manual-full.xml: ${MD_TARGETS} .version functions/library/locations.xml *.xml **/*.xml **/**/*.xml
 	xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
 
 .version:
 	nix-instantiate --eval \
 		-E '(import ../lib).version' > .version
 
+functions/library/locations.xml:
+	nix-build ./lib-function-locations.nix \
+		--out-link ./functions/library/locations.xml
+
 %.section.xml: %.section.md
 	pandoc $^ -w docbook+smart \
 		-f markdown+smart \

doc/default.nix

@@ -1,6 +1,7 @@
+{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
 let
-  pkgs = import ./.. { };
   lib = pkgs.lib;
+  locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
 in
 pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
@@ -29,6 +30,8 @@ pkgs.stdenv.mkDerivation {
   ];
 
   postPatch = ''
+    rm -rf ./functions/library/locations.xml
+    ln -s ${locationsXml} ./functions/library/locations.xml
     echo ${lib.version} > .version
   '';
 

doc/functions/library/asserts.xml

@@ -10,6 +10,8 @@
   <subtitle><literal>assertMsg :: Bool -> String -> Bool</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.asserts.assertMsg" />
+
   <para>
    Print a trace message if <literal>pred</literal> is false.
   </para>
@@ -59,6 +61,8 @@ stderr> assert failed
       StringList -> Bool</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.asserts.assertOneOf" />
+
   <para>
    Specialized <function>asserts.assertMsg</function> for checking if
    <varname>val</varname> is one of the elements of <varname>xs</varname>.

doc/functions/library/attrsets.xml

@@ -10,6 +10,8 @@
   <subtitle><literal>attrByPath :: [String] -> Any -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrByPath" />
+
   <para>
    Return an attribute from within nested attribute sets.
   </para>
@@ -73,6 +75,8 @@ lib.attrsets.attrByPath [ "a" "b" ] 0 {}
   <subtitle><literal>hasAttrByPath :: [String] -> AttrSet -> Bool</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.hasAttrByPath" />
+
   <para>
    Determine if an attribute exists within a nested attribute set.
   </para>
@@ -118,6 +122,8 @@ lib.attrsets.hasAttrByPath
   <subtitle><literal>setAttrByPath :: [String] -> Any -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.setAttrByPath" />
+
   <para>
    Create a new attribute set with <varname>value</varname> set at the nested
    attribute location specified in <varname>attrPath</varname>.
@@ -162,6 +168,8 @@ lib.attrsets.setAttrByPath [ "a" "b" ] 3
   <subtitle><literal>getAttrFromPath :: [String] -> AttrSet -> Value</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.getAttrFromPath" />
+
   <para>
    Like <xref linkend="function-library-lib.attrsets.attrByPath" /> except
    without a default, and it will throw if the value doesn't exist.
@@ -214,6 +222,8 @@ lib.attrsets.getAttrFromPath [ "x" "y" ] { }
   <subtitle><literal>attrVals :: [String] -> AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrVals" />
+
   <para>
    Return the specified attributes from a set. All values must exist.
   </para>
@@ -265,6 +275,8 @@ error: attribute 'd' missing
   <subtitle><literal>attrValues :: AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.attrValues" />
+
   <para>
    Get all the attribute values from an attribute set.
   </para>
@@ -302,6 +314,8 @@ lib.attrsets.attrValues { a = 1; b = 2; c = 3; }
   <subtitle><literal>catAttrs :: String -> AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.catAttrs" />
+
   <para>
    Collect each attribute named `attr' from the list of attribute sets,
    <varname>sets</varname>. Sets that don't contain the named attribute are
@@ -355,6 +369,8 @@ catAttrs "a" [{a = 1;} {b = 0;} {a = 2;}]
   <subtitle><literal>filterAttrs :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrs" />
+
   <para>
    Filter an attribute set by removing all attributes for which the given
    predicate return false.
@@ -428,6 +444,8 @@ filterAttrs (n: v: n == "foo") { foo = 1; bar = 2; }
   <subtitle><literal>filterAttrsRecursive :: (String -> Any -> Bool) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.filterAttrsRecursive" />
+
   <para>
    Filter an attribute set recursively by removing all attributes for which the
    given predicate return false.
@@ -523,6 +541,8 @@ lib.attrsets.filterAttrsRecursive
   <subtitle><literal>foldAttrs :: (Any -> Any -> Any) -> Any -> [AttrSets] -> Any</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.foldAttrs" />
+
   <para>
    Apply fold function to values grouped by key.
   </para>
@@ -609,6 +629,8 @@ lib.attrsets.foldAttrs
   <subtitle><literal>collect :: (Any -> Bool) -> AttrSet -> [Any]</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.collect" />
+
   <para>
    Recursively collect sets that verify a given predicate named
    <varname>pred</varname> from the set <varname>attrs</varname>. The recursion
@@ -677,6 +699,8 @@ collect (x: x ? outPath)
   <subtitle><literal>nameValuePair :: String -> Any -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.nameValuePair" />
+
   <para>
    Utility function that creates a <literal>{name, value}</literal> pair as
    expected by <function>builtins.listToAttrs</function>.
@@ -720,6 +744,8 @@ nameValuePair "some" 6
   <subtitle><literal></literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs" />
+
   <para>
    Apply a function to each element in an attribute set, creating a new
    attribute set.
@@ -785,6 +811,8 @@ lib.attrsets.mapAttrs
   <subtitle><literal>mapAttrs' :: (String -> Any -> { name = String; value = Any }) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrs-prime" />
+
   <para>
    Like <function>mapAttrs</function>, but allows the name of each attribute to
    be changed in addition to the value. The applied function should return both
@@ -860,6 +888,8 @@ lib.attrsets.mapAttrs' (name: value: lib.attrsets.nameValuePair ("foo_" + name)
    AttrSet -> Any</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsToList" />
+
   <para>
    Call <varname>fn</varname> for each attribute in the given
    <varname>set</varname> and return the result in a list.
@@ -929,6 +959,8 @@ lib.attrsets.mapAttrsToList (name: value: "${name}=${value}")
   <subtitle><literal>mapAttrsRecursive :: ([String] > Any -> Any) -> AttrSet -> AttrSet</literal>
   </subtitle>
 
+  <xi:include href="./locations.xml" xpointer="lib.attrsets.mapAttrsRecursive" />
+
   <para>
    Like <function>mapAttrs</function>, except that it recursively applies
    itself to attribute sets. Also, the first argument of the argument function

doc/lib-function-locations.nix

@@ -0,0 +1,85 @@
+{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
+let
+  revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master");
+
+  libDefPos = set:
+    builtins.map
+      (name: {
+        name = name;
+        location = builtins.unsafeGetAttrPos name set;
+      })
+      (builtins.attrNames set);
+
+  libset = toplib:
+    builtins.map
+      (subsetname: {
+        subsetname = subsetname;
+        functions = libDefPos toplib."${subsetname}";
+      })
+      (builtins.filter
+        (name: builtins.isAttrs toplib."${name}")
+        (builtins.attrNames toplib));
+
+  nixpkgsLib = pkgs.lib;
+
+  flattenedLibSubset = { subsetname, functions }:
+  builtins.map
+    (fn: {
+      name = "lib.${subsetname}.${fn.name}";
+      value = fn.location;
+    })
+    functions;
+
+  locatedlibsets = libs: builtins.map flattenedLibSubset (libset libs);
+  removeFilenamePrefix = prefix: filename:
+    let
+    prefixLen = (builtins.stringLength prefix) + 1; # +1 to remove the leading /
+      filenameLen = builtins.stringLength filename;
+      substr = builtins.substring prefixLen filenameLen filename;
+      in substr;
+
+  removeNixpkgs = removeFilenamePrefix (builtins.toString pkgs.path);
+
+  liblocations =
+    builtins.filter
+      (elem: elem.value != null)
+      (nixpkgsLib.lists.flatten
+        (locatedlibsets nixpkgsLib));
+
+  fnLocationRelative = { name, value }:
+    {
+      inherit name;
+      value = value // { file = removeNixpkgs value.file; };
+    };
+
+  relativeLocs = (builtins.map fnLocationRelative liblocations);
+  sanitizeId = builtins.replaceStrings
+    [ "'"      ]
+    [ "-prime" ];
+
+  urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";
+  xmlstrings = (nixpkgsLib.strings.concatMapStrings
+      ({ name, value }:
+      ''
+      <section><title>${name}</title>
+        <para xml:id="${sanitizeId name}">
+        Located at
+        <link
+          xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link>
+        in  <literal>&lt;nixpkgs&gt;</literal>.
+        </para>
+        </section>
+      '')
+      relativeLocs);
+
+in pkgs.writeText
+    "locations.xml"
+    ''
+    <section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         version="5">
+         <title>All the locations for every lib function</title>
+         <para>This file is only for inclusion by other files.</para>
+         ${xmlstrings}
+    </section>
+    ''

doc/shell.nix

@@ -1,5 +1,5 @@
 { pkgs ? import ../. {} }:
-(import ./default.nix).overrideAttrs (x: {
+(import ./default.nix {}).overrideAttrs (x: {
   buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ];
 
 })

pkgs/top-level/release.nix

@@ -8,7 +8,7 @@
 
    $ nix-build pkgs/top-level/release.nix -A coreutils.x86_64-linux
 */
-{ nixpkgs ? { outPath = (import ../../lib).cleanSource ../..; revCount = 1234; shortRev = "abcdef"; }
+{ nixpkgs ? { outPath = (import ../../lib).cleanSource ../..; revCount = 1234; shortRev = "abcdef"; revision = "0000000000000000000000000000000000000000"; }
 , officialRelease ? false
   # The platforms for which we build Nixpkgs.
 , supportedSystems ? [ "x86_64-linux" "x86_64-darwin" "aarch64-linux" ]
@@ -32,7 +32,7 @@ let
 
       metrics = import ./metrics.nix { inherit pkgs nixpkgs; };
 
-      manual = import ../../doc;
+      manual = import ../../doc { inherit pkgs nixpkgs; };
       lib-tests = import ../../lib/tests/release.nix { inherit pkgs; };
 
       darwin-tested = if supportDarwin then pkgs.releaseTools.aggregate