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.
This commit is contained in:
Graham Christensen 2018-10-05 10:46:58 -04:00
parent 4312cfdbda
commit 5daee73ce4
No known key found for this signature in database
GPG Key ID: ACA1C1D120C83D5C
8 changed files with 135 additions and 6 deletions

1
doc/.gitignore vendored
View File

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

View File

@ -19,7 +19,7 @@ fix-misc-xml:
.PHONY: clean .PHONY: clean
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 rm -rf ./out/ ./highlightjs
.PHONY: validate .PHONY: validate
@ -69,13 +69,17 @@ highlightjs:
cp -r "$$HIGHLIGHTJS/loader.js" 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 xmllint --nonet --xinclude --noxincludenode manual.xml --output manual-full.xml
.version: .version:
nix-instantiate --eval \ nix-instantiate --eval \
-E '(import ../lib).version' > .version -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 %.section.xml: %.section.md
pandoc $^ -w docbook+smart \ pandoc $^ -w docbook+smart \
-f markdown+smart \ -f markdown+smart \

View File

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

View File

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

View File

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

View File

@ -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>
''

View File

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

View File

@ -8,7 +8,7 @@
$ nix-build pkgs/top-level/release.nix -A coreutils.x86_64-linux $ 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 , officialRelease ? false
# The platforms for which we build Nixpkgs. # The platforms for which we build Nixpkgs.
, supportedSystems ? [ "x86_64-linux" "x86_64-darwin" "aarch64-linux" ] , supportedSystems ? [ "x86_64-linux" "x86_64-darwin" "aarch64-linux" ]
@ -32,7 +32,7 @@ let
metrics = import ./metrics.nix { inherit pkgs nixpkgs; }; 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; }; lib-tests = import ../../lib/tests/release.nix { inherit pkgs; };
darwin-tested = if supportDarwin then pkgs.releaseTools.aggregate darwin-tested = if supportDarwin then pkgs.releaseTools.aggregate