Merge pull request #8330 from NixOS/doc-auto-builtin-constants

Automatically document builtin constants

6 files changed, 57 insertions, 55 deletions

diff --git a/doc/manual/generate-builtin-constants.nix b/doc/manual/generate-builtin-constants.nix
new file mode 100644
index 000000000..3fc1fae42
--- /dev/null
+++ b/doc/manual/generate-builtin-constants.nix
@@ -0,0 +1,29 @@
+let
+  inherit (builtins) concatStringsSep attrValues mapAttrs;
+  inherit (import ./utils.nix) optionalString squash;
+in
+
+builtinsInfo:
+let
+  showBuiltin = name: { doc, type, impure-only }:
+    let
+      type' = optionalString (type != null) " (${type})";
+
+      impureNotice = optionalString impure-only ''
+        Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
+      '';
+    in
+    squash ''
+      <dt id="builtin-constants-${name}">
+        <a href="#builtin-constants-${name}"><code>${name}</code>${type'}</a>
+      </dt>
+      <dd>
+
+      ${doc}
+
+      ${impureNotice}
+
+      </dd>
+    '';
+in
+concatStringsSep "\n" (attrValues (mapAttrs showBuiltin builtinsInfo))
diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix
index 71f96153f..813a287f5 100644
--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@@ -1,24 +1,28 @@
 let
-  inherit (builtins) concatStringsSep attrNames;
+  inherit (builtins) concatStringsSep attrValues mapAttrs;
+  inherit (import ./utils.nix) optionalString squash;
 in
 
 builtinsInfo:
 let
-  showBuiltin = name:
+  showBuiltin = name: { doc, args, arity, experimental-feature }:
     let
-      inherit (builtinsInfo.${name}) doc args;
+      experimentalNotice = optionalString (experimental-feature != null) ''
+        This function is only available if the [${experimental-feature}](@docroot@/contributing/experimental-features.md#xp-feature-${experimental-feature}) experimental feature is enabled.
+      '';
     in
-    ''
+    squash ''
       <dt id="builtins-${name}">
         <a href="#builtins-${name}"><code>${name} ${listArgs args}</code></a>
       </dt>
       <dd>
 
-        ${doc}
+      ${doc}
+
+      ${experimentalNotice}
 
       </dd>
     '';
   listArgs = args: concatStringsSep " " (map (s: "<var>${s}</var>") args);
 in
-concatStringsSep "\n" (map showBuiltin (attrNames builtinsInfo))
-
+concatStringsSep "\n" (attrValues (mapAttrs showBuiltin builtinsInfo))
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index b4b7283ef..abdfd6a62 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -128,14 +128,20 @@ $(d)/xp-features.json: $(bindir)/nix
 	$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-xp-features > $@.tmp
 	@mv $@.tmp $@
 
-$(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
+$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
 	@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@.tmp;
 	@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
 	@mv $@.tmp $@
 
-$(d)/builtins.json: $(bindir)/nix
-	$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-builtins > $@.tmp
+$(d)/src/language/builtin-constants.md: $(d)/language.json $(d)/generate-builtin-constants.nix $(d)/src/language/builtin-constants-prefix.md $(bindir)/nix
+	@cat doc/manual/src/language/builtin-constants-prefix.md > $@.tmp
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@.tmp;
+	@cat doc/manual/src/language/builtin-constants-suffix.md >> $@.tmp
+	@mv $@.tmp $@
+
+$(d)/language.json: $(bindir)/nix
+	$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-language > $@.tmp
 	@mv $@.tmp $@
 
 # Generate the HTML manual.
@@ -167,7 +173,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 	done
 	@touch $@
 
-$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md
+$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md
 	$(trace-gen) \
 		tmp="$$(mktemp -d)"; \
 		cp -r doc/manual "$$tmp"; \
diff --git a/doc/manual/src/language/builtin-constants-prefix.md b/doc/manual/src/language/builtin-constants-prefix.md
new file mode 100644
index 000000000..50f43006d
--- /dev/null
+++ b/doc/manual/src/language/builtin-constants-prefix.md
@@ -0,0 +1,5 @@
+# Built-in Constants
+
+These constants are built into the Nix language evaluator:
+
+<dl>
diff --git a/doc/manual/src/language/builtin-constants-suffix.md b/doc/manual/src/language/builtin-constants-suffix.md
new file mode 100644
index 000000000..a74db2857
--- /dev/null
+++ b/doc/manual/src/language/builtin-constants-suffix.md
@@ -0,0 +1 @@
+</dl>
diff --git a/doc/manual/src/language/builtin-constants.md b/doc/manual/src/language/builtin-constants.md
deleted file mode 100644
index e6bc7e915..000000000
--- a/doc/manual/src/language/builtin-constants.md
+++ /dev/null
@@ -1,43 +0,0 @@
-# Built-in Constants
-
-These constants are built into the Nix language evaluator:
-
-- [`builtins`]{#builtins-builtins} (attribute set)
-
-  Contains all the [built-in functions](./builtins.md) and values, in order to avoid polluting the global scope.
-
-  Since built-in functions were added over time, [testing for attributes](./operators.md#has-attribute) in `builtins` can be used for graceful fallback on older Nix installations:
-
-  ```nix
-  if builtins ? getEnv then builtins.getEnv "PATH" else ""
-  ```
-
-- [`builtins.currentSystem`]{#builtins-currentSystem} (string)
-
-  The built-in value `currentSystem` evaluates to the Nix platform
-  identifier for the Nix installation on which the expression is being
-  evaluated, such as `"i686-linux"` or `"x86_64-darwin"`.
-
-  Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).
-
-- [`builtins.currentTime`]{#builtins-currentTime} (integer)
-
-  Return the [Unix time](https://en.wikipedia.org/wiki/Unix_time) at first evaluation.
-  Repeated references to that name will re-use the initially obtained value.
-
-  Example:
-
-  ```console
-  $ nix repl
-  Welcome to Nix 2.15.1 Type :? for help.
-
-  nix-repl> builtins.currentTime
-  1683705525
-
-  nix-repl> builtins.currentTime
-  1683705525
-  ```
-
-  The [store path](@docroot@/glossary.md#gloss-store-path) of a derivation depending on `currentTime` will differ for each evaluation.
-
-  Not available in [pure evaluation mode](@docroot@/command-ref/conf-file.md#conf-pure-eval).