diff options
author | Graham Christensen <graham@grahamc.com> | 2019-07-04 08:23:39 -0400 |
---|---|---|
committer | Graham Christensen <graham@grahamc.com> | 2019-07-04 09:07:47 -0400 |
commit | cd6bf8aa00962766e4db9f26e36848b6be8dd096 (patch) | |
tree | bdcca190ea7a29c855f8ac63735566dc1f775ade /doc/doc-support | |
parent | ddfe184efcc2152b741bc0a8eee3dea12c4cb2f8 (diff) |
docs: use a single nix-build for all the generate function docs
Diffstat (limited to 'doc/doc-support')
-rw-r--r-- | doc/doc-support/default.nix | 14 | ||||
-rw-r--r-- | doc/doc-support/lib-function-docs.nix | 26 | ||||
-rw-r--r-- | doc/doc-support/lib-function-locations.nix | 85 |
3 files changed, 125 insertions, 0 deletions
diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix new file mode 100644 index 000000000000..93f6287d4b09 --- /dev/null +++ b/doc/doc-support/default.nix @@ -0,0 +1,14 @@ +{ pkgs ? (import ../.. {}), nixpkgs ? { }}: +let + locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; }; + functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; }; +in pkgs.runCommand "doc-support" {} +'' + mkdir result + ( + cd result + ln -s ${locationsXml} ./function-locations.xml + ln -s ${functionDocs} ./function-docs + ) + mv result $out +'' diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix new file mode 100644 index 000000000000..5199b949e7b8 --- /dev/null +++ b/doc/doc-support/lib-function-docs.nix @@ -0,0 +1,26 @@ +# Generates the documentation for library functons via nixdoc. To add +# another library function file to this list, the include list in the +# file `doc/functions/library.xml` must also be updated. + +{ pkgs ? import ./.. {}, locationsXml }: + +with pkgs; stdenv.mkDerivation { + name = "nixpkgs-lib-docs"; + src = ./../../lib; + + buildInputs = [ nixdoc ]; + installPhase = '' + function docgen { + nixdoc -c "$1" -d "$2" -f "../lib/$1.nix" > "$out/$1.xml" + } + + mkdir -p $out + ln -s ${locationsXml} $out/locations.xml + + docgen strings 'String manipulation functions' + docgen trivial 'Miscellaneous functions' + docgen lists 'List manipulation functions' + docgen debug 'Debugging functions' + docgen options 'NixOS / nixpkgs option handling' + ''; +} diff --git a/doc/doc-support/lib-function-locations.nix b/doc/doc-support/lib-function-locations.nix new file mode 100644 index 000000000000..ae7036e46264 --- /dev/null +++ b/doc/doc-support/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><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> + '' |