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
manual-full.xml
highlightjs
functions/library/locations.xml

View file

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

View file

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

View file

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

View file

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

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 ../. {} }:
(import ./default.nix).overrideAttrs (x: {
(import ./default.nix {}).overrideAttrs (x: {
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
*/
{ 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