Merge master into staging-next

2 files changed, 30 insertions, 0 deletions

diff --git a/doc/build-helpers.md b/doc/build-helpers.md
index 06737e166760..010665484cfd 100644
--- a/doc/build-helpers.md
+++ b/doc/build-helpers.md
@@ -20,6 +20,7 @@ There is no uniform interface for build helpers.
 build-helpers/fetchers.chapter.md
 build-helpers/trivial-build-helpers.chapter.md
 build-helpers/testers.chapter.md
+build-helpers/dev-shell-tools.chapter.md
 build-helpers/special.md
 build-helpers/images.md
 hooks/index.md
diff --git a/doc/build-helpers/dev-shell-tools.chapter.md b/doc/build-helpers/dev-shell-tools.chapter.md
new file mode 100644
index 000000000000..21636df8017b
--- /dev/null
+++ b/doc/build-helpers/dev-shell-tools.chapter.md
@@ -0,0 +1,29 @@
+# Development Shell helpers {#chap-devShellTools}
+
+The `nix-shell` command has popularized the concept of transient shell environments for development or testing purposes.
+<!--
+  We should try to document the product, not its development process in the Nixpkgs reference manual,
+  but *something* needs to be said to provide context for this library.
+  This is the most future proof sentence I could come up with while Nix itself does yet make use of this.
+  Relevant is the current status of the devShell attribute "project": https://github.com/NixOS/nix/issues/7501
+  -->
+However, `nix-shell` is not the only way to create such environments, and even `nix-shell` itself can indirectly benefit from this library.
+
+This library provides a set of functions that help create such environments.
+
+## `devShellTools.valueToString` {#sec-devShellTools-valueToString}
+
+Converts Nix values to strings in the way the [`derivation` built-in function](https://nix.dev/manual/nix/2.23/language/derivations) does.
+
+:::{.example}
+## `valueToString` usage examples
+
+```nix
+devShellTools.valueToString (builtins.toFile "foo" "bar")
+=> "/nix/store/...-foo"
+```
+
+```nix
+devShellTools.valueToString false
+=> ""
+```