1 files changed, 27 insertions, 0 deletions
diff --git a/doc/functions/shell.xml b/doc/functions/shell.xml
new file mode 100644
index 000000000000..a8d2a30cb508
--- /dev/null
+++ b/doc/functions/shell.xml
@@ -0,0 +1,27 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         xml:id="sec-pkgs-mkShell">
+  <title>pkgs.mkShell</title>
+
+  <para>
+    <function>pkgs.mkShell</function> is a special kind of derivation
+    that is only useful when using it combined with
+    <command>nix-shell</command>. It will in fact fail to instantiate
+    when invoked with <command>nix-build</command>.
+  </para>
+
+  <section xml:id="sec-pkgs-mkShell-usage">
+    <title>Usage</title>
+
+    <programlisting><![CDATA[
+{ pkgs ? import <nixpkgs> {} }:
+pkgs.mkShell {
+  # this will make all the build inputs from hello and gnutar
+  # available to the shell environment
+  inputsFrom = with pkgs; [ hello gnutar ];
+  buildInputs = [ pkgs.gnumake ];
+}
+]]></programlisting>
+  </section>
+</section>