doc/doc-support/lib-function-locations.nix

   1 { pkgs ? (import ./.. { }), nixpkgs ? { }}:
   2 let
   3   revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master");
   4
   5   libDefPos = set:
   6     builtins.map
   7       (name: {
   8         name = name;
   9         location = builtins.unsafeGetAttrPos name set;
  10       })
  11       (builtins.attrNames set);
  12
  13   libset = toplib:
  14     builtins.map
  15       (subsetname: {
  16         subsetname = subsetname;
  17         functions = libDefPos toplib.${subsetname};
  18       })
  19       (builtins.filter
  20         (name: builtins.isAttrs toplib.${name})
  21         (builtins.attrNames toplib));
  22
  23   nixpkgsLib = pkgs.lib;
  24
  25   flattenedLibSubset = { subsetname, functions }:
  26   builtins.map
  27     (fn: {
  28       name = "lib.${subsetname}.${fn.name}";
  29       value = fn.location;
  30     })
  31     functions;
  32
  33   locatedlibsets = libs: builtins.map flattenedLibSubset (libset libs);
  34   removeFilenamePrefix = prefix: filename:
  35     let
  36     prefixLen = (builtins.stringLength prefix) + 1; # +1 to remove the leading /
  37       filenameLen = builtins.stringLength filename;
  38       substr = builtins.substring prefixLen filenameLen filename;
  39       in substr;
  40
  41   removeNixpkgs = removeFilenamePrefix (builtins.toString pkgs.path);
  42
  43   liblocations =
  44     builtins.filter
  45       (elem: elem.value != null)
  46       (nixpkgsLib.lists.flatten
  47         (locatedlibsets nixpkgsLib));
  48
  49   fnLocationRelative = { name, value }:
  50     {
  51       inherit name;
  52       value = value // { file = removeNixpkgs value.file; };
  53     };
  54
  55   relativeLocs = (builtins.map fnLocationRelative liblocations);
  56   sanitizeId = builtins.replaceStrings
  57     [ "'"      ]
  58     [ "-prime" ];
  59
  60   urlPrefix = "https://github.com/NixOS/nixpkgs/blob/${revision}";
  61   xmlstrings = (nixpkgsLib.strings.concatMapStrings
  62       ({ name, value }:
  63       ''
  64       <section><title>${name}</title>
  65         <para xml:id="${sanitizeId name}">
  66         Located at
  67         <link
  68           xlink:href="${urlPrefix}/${value.file}#L${builtins.toString value.line}">${value.file}:${builtins.toString value.line}</link>
  69         in  <literal>&lt;nixpkgs&gt;</literal>.
  70         </para>
  71         </section>
  72       '')
  73       relativeLocs);
  74
  75 in pkgs.writeText
  76     "locations.xml"
  77     ''
  78     <section xmlns="http://docbook.org/ns/docbook"
  79          xmlns:xlink="http://www.w3.org/1999/xlink"
  80          version="5">
  81          <title>All the locations for every lib function</title>
  82          <para>This file is only for inclusion by other files.</para>
  83          ${xmlstrings}
  84     </section>
  85     ''