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.

7 files changed, 133 insertions, 4 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
index d0ba103fa9f1..cb07135e6858 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -4,3 +4,4 @@
 out
 manual-full.xml
 highlightjs
+functions/library/locations.xml
diff --git a/doc/Makefile b/doc/Makefile
index 65a37eb05a3a..c6aed62a9396 100644
--- a/doc/Makefile
+++ b/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 \
diff --git a/doc/default.nix b/doc/default.nix
index 4c04128052bc..98b4b92be524 100644
--- a/doc/default.nix
+++ b/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
   '';
 
diff --git a/doc/functions/library/asserts.xml b/doc/functions/library/asserts.xml
index 1f42078c8cf3..437850e408bc 100644
--- a/doc/functions/library/asserts.xml
+++ b/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>.
diff --git a/doc/functions/library/attrsets.xml b/doc/functions/library/attrsets.xml
index 7ad3f949a024..6f23e267bab2 100644
--- a/doc/functions/library/attrsets.xml
+++ b/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
diff --git a/doc/lib-function-locations.nix b/doc/lib-function-locations.nix
new file mode 100644
index 000000000000..ae7036e46264
--- /dev/null
+++ b/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>
+    ''
diff --git a/doc/shell.nix b/doc/shell.nix
index 24fe20e81050..8ac2019f9d66 100644
--- a/doc/shell.nix
+++ b/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 ];
 
 })