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.
2018-10-05 10:46:58 -04:00 · 2018-10-05 10:46:58 -04:00 · 5daee73ce4
parent 4312cfdbda
commit 5daee73ce4
8 changed files with 135 additions and 6 deletions
--- a/doc/.gitignore
+++ b/doc/.gitignore
@ -4,3 +4,4 @@
 out
 manual-full.xml
 highlightjs
+functions/library/locations.xml
--- 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 \
--- 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
  '';

--- 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>.
--- 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
--- a/doc/lib-function-locations.nix
+++ 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>
+    ''
--- 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 ];

 })
--- a/pkgs/top-level/release.nix
+++ b/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