From 8906aa28e4de1f1b53a99691c1373292f1106766 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Na=C3=AFm=20Favier?= Date: Sun, 11 Dec 2022 15:56:09 +0100 Subject: [PATCH 1/4] 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`. --- doc/doc-support/default.nix | 16 ++++++++-- doc/doc-support/lib-function-docs.nix | 35 +++++++++++----------- doc/doc-support/lib-function-locations.nix | 6 ++-- doc/doc-support/parameters.xml | 1 + doc/functions/library.xml | 24 ++------------- 5 files changed, 38 insertions(+), 44 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 "" >> "$out/index.xml" } - mkdir -p $out - ln -s ${locationsXml} $out/locations.xml + mkdir -p "$out" + + cat > "$out/index.xml" << 'EOF' + + + 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 "" >> "$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 @@ + diff --git a/doc/functions/library.xml b/doc/functions/library.xml index 0a8bae229f261..788ea0b94f1fe 100644 --- a/doc/functions/library.xml +++ b/doc/functions/library.xml @@ -8,25 +8,7 @@ Nixpkgs provides a standard library at pkgs.lib, or through import <nixpkgs/lib>. - - - - - - - - - - - - - - - - - - - + + From e1bb8f1e74895b6c4365e0fb7dcded9f69d39358 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Na=C3=AFm=20Favier?= Date: Sun, 11 Dec 2022 17:01:02 +0100 Subject: [PATCH 2/4] doc/lib-functions: add `versions`, `cli` --- doc/doc-support/default.nix | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix index 0b188c7000105..d8ac4a6787b23 100644 --- a/doc/doc-support/default.nix +++ b/doc/doc-support/default.nix @@ -7,12 +7,14 @@ let asserts = "Assert functions"; attrsets = "Attribute-set functions"; strings = "String manipulation functions"; + versions = "Version string functions"; trivial = "Miscellaneous functions"; lists = "List manipulation functions"; debug = "Debugging functions"; options = "NixOS / nixpkgs option handling"; filesystem = "Filesystem functions"; sources = "Source filtering functions"; + cli = "Command-line serialization functions"; }; locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; }; From ce952286ca8a37e8c63d9627aec2f0dc2c2913f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Na=C3=AFm=20Favier?= Date: Mon, 12 Dec 2022 12:21:59 +0100 Subject: [PATCH 3/4] doc/lib-functions: preserve libsets order --- doc/doc-support/default.nix | 26 +++++++++++----------- doc/doc-support/lib-function-docs.nix | 4 ++-- doc/doc-support/lib-function-locations.nix | 2 +- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix index d8ac4a6787b23..c55df4ce870e5 100644 --- a/doc/doc-support/default.nix +++ b/doc/doc-support/default.nix @@ -3,19 +3,19 @@ let inherit (pkgs) lib; inherit (lib) hasPrefix removePrefix; - libsets = { - asserts = "Assert functions"; - attrsets = "Attribute-set functions"; - strings = "String manipulation functions"; - versions = "Version string functions"; - trivial = "Miscellaneous functions"; - lists = "List manipulation functions"; - debug = "Debugging functions"; - options = "NixOS / nixpkgs option handling"; - filesystem = "Filesystem functions"; - sources = "Source filtering functions"; - cli = "Command-line serialization functions"; - }; + libsets = [ + { name = "asserts"; description = "Assert functions"; } + { name = "attrsets"; description = "Attribute-set functions"; } + { name = "strings"; description = "String manipulation functions"; } + { name = "versions"; description = "Version string functions"; } + { name = "trivial"; description = "Miscellaneous functions"; } + { name = "lists"; description = "List manipulation functions"; } + { name = "debug"; description = "Debugging functions"; } + { name = "options"; description = "NixOS / nixpkgs option handling"; } + { name = "filesystem"; description = "Filesystem functions"; } + { name = "sources"; description = "Source filtering functions"; } + { name = "cli"; description = "Command-line serialization functions"; } + ]; locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; }; functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs libsets; }; diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix index a11de1a9f6f1b..d3d90d98c9814 100644 --- a/doc/doc-support/lib-function-docs.nix +++ b/doc/doc-support/lib-function-docs.nix @@ -20,9 +20,9 @@ with pkgs; stdenv.mkDerivation { EOF - ${lib.concatStrings (lib.mapAttrsToList (name: description: '' + ${lib.concatMapStrings ({ name, description }: '' docgen ${name} ${lib.escapeShellArg description} - '') libsets)} + '') libsets} echo "" >> "$out/index.xml" diff --git a/doc/doc-support/lib-function-locations.nix b/doc/doc-support/lib-function-locations.nix index 7db176256e0ae..ae1123c63ad30 100644 --- a/doc/doc-support/lib-function-locations.nix +++ b/doc/doc-support/lib-function-locations.nix @@ -16,7 +16,7 @@ let subsetname = subsetname; functions = libDefPos toplib.${subsetname}; }) - (builtins.attrNames libsets); + (builtins.map (x: x.name) libsets); nixpkgsLib = pkgs.lib; From 5782c3d802d9c8dc8bfb2901d3dba6cc7d47056f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Na=C3=AFm=20Favier?= Date: Mon, 12 Dec 2022 13:17:47 +0100 Subject: [PATCH 4/4] doc/lib-functions: print libset name before description --- doc/doc-support/default.nix | 20 ++++++++++---------- doc/doc-support/lib-function-docs.nix | 3 ++- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/doc/doc-support/default.nix b/doc/doc-support/default.nix index c55df4ce870e5..ec180064c35d8 100644 --- a/doc/doc-support/default.nix +++ b/doc/doc-support/default.nix @@ -4,17 +4,17 @@ let inherit (lib) hasPrefix removePrefix; libsets = [ - { name = "asserts"; description = "Assert functions"; } - { name = "attrsets"; description = "Attribute-set functions"; } - { name = "strings"; description = "String manipulation functions"; } - { name = "versions"; description = "Version string functions"; } - { name = "trivial"; description = "Miscellaneous functions"; } - { name = "lists"; description = "List manipulation functions"; } - { name = "debug"; description = "Debugging functions"; } + { name = "asserts"; description = "assertion functions"; } + { name = "attrsets"; description = "attribute set functions"; } + { name = "strings"; description = "string manipulation functions"; } + { name = "versions"; description = "version string functions"; } + { name = "trivial"; description = "miscellaneous functions"; } + { name = "lists"; description = "list manipulation functions"; } + { name = "debug"; description = "debugging functions"; } { name = "options"; description = "NixOS / nixpkgs option handling"; } - { name = "filesystem"; description = "Filesystem functions"; } - { name = "sources"; description = "Source filtering functions"; } - { name = "cli"; description = "Command-line serialization functions"; } + { name = "filesystem"; description = "filesystem functions"; } + { name = "sources"; description = "source filtering functions"; } + { name = "cli"; description = "command-line serialization functions"; } ]; locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs libsets; }; diff --git a/doc/doc-support/lib-function-docs.nix b/doc/doc-support/lib-function-docs.nix index d3d90d98c9814..d6fa08aa96205 100644 --- a/doc/doc-support/lib-function-docs.nix +++ b/doc/doc-support/lib-function-docs.nix @@ -9,7 +9,8 @@ with pkgs; stdenv.mkDerivation { buildInputs = [ nixdoc ]; installPhase = '' function docgen { - nixdoc -c "$1" -d "$2" -f "$1.nix" > "$out/$1.xml" + # TODO: wrap lib.$1 in , make nixdoc not escape it + nixdoc -c "$1" -d "lib.$1: $2" -f "$1.nix" > "$out/$1.xml" echo "" >> "$out/index.xml" }