diff options
author | Naïm Favier <n@monade.li> | 2022-12-11 15:56:09 +0100 |
---|---|---|
committer | Naïm Favier <n@monade.li> | 2022-12-22 11:31:08 +0100 |
commit | 8906aa28e4de1f1b53a99691c1373292f1106766 (patch) | |
tree | 075ff85215c4658a0e8e93b9cac12051ae1962bf /doc/doc-support | |
parent | cd39b90b6f5c7333116c75b1cb9a132cf2d56714 (diff) |
doc/lib-functions: remove warnings
Building the nixpkgs manual currently triggers a bunch of deprecation warnings, because every attribute in `lib` is evaluated to see if it's an attrset to generate locations for. Instead, share the lib subsets to include in the documentation between `lib-function-docs` and `lib-function-locations` so they can coordinate. Also generate the list of sections instead of duplicating it in `library.xml`.
Diffstat (limited to 'doc/doc-support')
-rw-r--r-- | doc/doc-support/default.nix | 16 | ||||
-rw-r--r-- | doc/doc-support/lib-function-docs.nix | 35 | ||||
-rw-r--r-- | doc/doc-support/lib-function-locations.nix | 6 | ||||
-rw-r--r-- | doc/doc-support/parameters.xml | 1 |
4 files changed, 35 insertions, 23 deletions
diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix index 429c7a5fbe800..0b188c7000105 100644 --- a/doc/doc-support/default.nix +++ b/doc/doc-support/default.nix @@ -3,8 +3,20 @@ let inherit (pkgs) lib; inherit (lib) hasPrefix removePrefix; - locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; }; - functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; }; + libsets = { + asserts = "Assert functions"; + attrsets = "Attribute-set functions"; + strings = "String manipulation functions"; + trivial = "Miscellaneous functions"; + lists = "List manipulation functions"; + debug = "Debugging functions"; + options = "NixOS / nixpkgs option handling"; + filesystem = "Filesystem functions"; + sources = "Source filtering functions"; + }; + + locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; }; + functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs libsets; }; version = pkgs.lib.version; epub-xsl = pkgs.writeText "epub.xsl" '' diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix index 4e67609e23fb2..a11de1a9f6f1b 100644 --- a/doc/doc-support/lib-function-docs.nix +++ b/doc/doc-support/lib-function-docs.nix @@ -1,30 +1,31 @@ -# Generates the documentation for library functions 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. +# Generates the documentation for library functions via nixdoc. -{ pkgs ? import ./.. {}, locationsXml }: +{ pkgs, locationsXml, libsets }: with pkgs; stdenv.mkDerivation { name = "nixpkgs-lib-docs"; - src = ./../../lib; + src = ../../lib; buildInputs = [ nixdoc ]; installPhase = '' function docgen { - nixdoc -c "$1" -d "$2" -f "../lib/$1.nix" > "$out/$1.xml" + nixdoc -c "$1" -d "$2" -f "$1.nix" > "$out/$1.xml" + echo "<xi:include href='$1.xml' />" >> "$out/index.xml" } - mkdir -p $out - ln -s ${locationsXml} $out/locations.xml + mkdir -p "$out" + + cat > "$out/index.xml" << 'EOF' + <?xml version="1.0" encoding="utf-8"?> + <root xmlns:xi="http://www.w3.org/2001/XInclude"> + EOF + + ${lib.concatStrings (lib.mapAttrsToList (name: description: '' + docgen ${name} ${lib.escapeShellArg description} + '') libsets)} - docgen asserts 'Assert functions' - docgen attrsets 'Attribute-set functions' - docgen strings 'String manipulation functions' - docgen trivial 'Miscellaneous functions' - docgen lists 'List manipulation functions' - docgen debug 'Debugging functions' - docgen options 'NixOS / nixpkgs option handling' - docgen filesystem 'Filesystem functions' - docgen sources 'Source filtering functions' + echo "</root>" >> "$out/index.xml" + + ln -s ${locationsXml} $out/locations.xml ''; } diff --git a/doc/doc-support/lib-function-locations.nix b/doc/doc-support/lib-function-locations.nix index 68edd27098543..7db176256e0ae 100644 --- a/doc/doc-support/lib-function-locations.nix +++ b/doc/doc-support/lib-function-locations.nix @@ -1,4 +1,4 @@ -{ pkgs ? (import ./.. { }), nixpkgs ? { }}: +{ pkgs, nixpkgs ? { }, libsets }: let revision = pkgs.lib.trivial.revisionWithDefault (nixpkgs.revision or "master"); @@ -16,9 +16,7 @@ let subsetname = subsetname; functions = libDefPos toplib.${subsetname}; }) - (builtins.filter - (name: builtins.isAttrs toplib.${name}) - (builtins.attrNames toplib)); + (builtins.attrNames libsets); nixpkgsLib = pkgs.lib; diff --git a/doc/doc-support/parameters.xml b/doc/doc-support/parameters.xml index 50ff25fe10750..5b39d2f7f1a58 100644 --- a/doc/doc-support/parameters.xml +++ b/doc/doc-support/parameters.xml @@ -11,6 +11,7 @@ <xsl:param name="html.script" select="'./highlightjs/highlight.pack.js ./highlightjs/loader.js'" /> <xsl:param name="xref.with.number.and.title" select="0" /> <xsl:param name="use.id.as.filename" select="1" /> + <xsl:param name="generate.section.toc.level" select="1" /> <xsl:param name="toc.section.depth" select="0" /> <xsl:param name="admon.style" select="''" /> <xsl:param name="callout.graphics.extension" select="'.svg'" /> |