Merge pull request #47920 from grahamc/link-to-definition
docs: Link to Definition
This commit is contained in:
commit
b4755393cc
1
doc/.gitignore
vendored
1
doc/.gitignore
vendored
@ -4,3 +4,4 @@
|
||||
out
|
||||
manual-full.xml
|
||||
highlightjs
|
||||
functions/library/locations.xml
|
||||
|
@ -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 \
|
||||
|
@ -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
|
||||
'';
|
||||
|
||||
|
@ -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>.
|
||||
|
@ -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
|
||||
|
85
doc/lib-function-locations.nix
Normal file
85
doc/lib-function-locations.nix
Normal 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><nixpkgs></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>
|
||||
''
|
@ -1,5 +1,5 @@
|
||||
{ pkgs ? import ../. {} }:
|
||||
(import ./default.nix).overrideAttrs (x: {
|
||||
(import ./default.nix {}).overrideAttrs (x: {
|
||||
buildInputs = x.buildInputs ++ [ pkgs.xmloscopy pkgs.ruby ];
|
||||
|
||||
})
|
||||
|
@ -105,6 +105,16 @@ rec {
|
||||
then lib.strings.fileContents suffixFile
|
||||
else "pre-git";
|
||||
|
||||
# Attempt to get the revision nixpkgs is from
|
||||
revisionWithDefault = default:
|
||||
let
|
||||
revisionFile = "${toString ./..}/.git-revision";
|
||||
gitRepo = "${toString ./..}/.git";
|
||||
in if lib.pathIsDirectory gitRepo
|
||||
then lib.commitIdFromGitRepo gitRepo
|
||||
else if lib.pathExists revisionFile then lib.fileContents revisionFile
|
||||
else default;
|
||||
|
||||
nixpkgsVersion = builtins.trace "`lib.nixpkgsVersion` is deprecated, use `lib.version` instead!" version;
|
||||
|
||||
# Whether we're being called by nix-shell.
|
||||
|
@ -5,7 +5,6 @@ with lib;
|
||||
let
|
||||
cfg = config.system.nixos;
|
||||
|
||||
revisionFile = "${toString pkgs.path}/.git-revision";
|
||||
gitRepo = "${toString pkgs.path}/.git";
|
||||
gitCommitId = lib.substring 0 7 (commitIdFromGitRepo gitRepo);
|
||||
in
|
||||
@ -37,9 +36,7 @@ in
|
||||
nixos.revision = mkOption {
|
||||
internal = true;
|
||||
type = types.str;
|
||||
default = if pathIsDirectory gitRepo then commitIdFromGitRepo gitRepo
|
||||
else if pathExists revisionFile then fileContents revisionFile
|
||||
else "master";
|
||||
default = lib.trivial.revisionWithDefault "master";
|
||||
description = "The Git revision from which this NixOS configuration was built.";
|
||||
};
|
||||
|
||||
|
@ -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
|
||||
|
Loading…
x
Reference in New Issue
Block a user