7 files changed, 180 insertions, 0 deletions
diff --git a/nixpkgs/doc/functions/debug.section.md b/nixpkgs/doc/functions/debug.section.md
new file mode 100644
index 000000000000..b2d8589431ab
--- /dev/null
+++ b/nixpkgs/doc/functions/debug.section.md
@@ -0,0 +1,5 @@
+# Debugging Nix Expressions {#sec-debug}
+
+Nix is a unityped, dynamic language, this means every value can potentially appear anywhere. Since it is also non-strict, evaluation order and what ultimately is evaluated might surprise you. Therefore it is important to be able to debug nix expressions.
+
+In the `lib/debug.nix` file you will find a number of functions that help (pretty-)printing values while evaluation is running. You can even specify how deep these values should be printed recursively, and transform them on the fly. Please consult the docstrings in `lib/debug.nix` for usage information.
diff --git a/nixpkgs/doc/functions/fileset.section.md b/nixpkgs/doc/functions/fileset.section.md
new file mode 100644
index 000000000000..c42337feaba4
--- /dev/null
+++ b/nixpkgs/doc/functions/fileset.section.md
@@ -0,0 +1,48 @@
+<!-- TODO: Render this document in front of function documentation in case https://github.com/nix-community/nixdoc/issues/19 is ever supported -->
+
+# File sets {#sec-fileset}
+
+The [`lib.fileset`](#sec-functions-library-fileset) library allows you to work with _file sets_.
+A file set is a mathematical set of local files that can be added to the Nix store for use in Nix derivations.
+File sets are easy and safe to use, providing obvious and composable semantics with good error messages to prevent mistakes.
+
+See the [function reference](#sec-functions-library-fileset) for function-specific documentation.
+
+## Implicit coercion from paths to file sets {#sec-fileset-path-coercion}
+
+All functions accepting file sets as arguments can also accept [paths](https://nixos.org/manual/nix/stable/language/values.html#type-path) as arguments.
+Such path arguments are implicitly coerced to file sets containing all files under that path:
+- A path to a file turns into a file set containing that single file.
+- A path to a directory turns into a file set containing all files _recursively_ in that directory.
+
+If the path points to a non-existent location, an error is thrown.
+
+::: {.note}
+Just like in Git, file sets cannot represent empty directories.
+Because of this, a path to a directory that contains no files (recursively) will turn into a file set containing no files.
+:::
+
+:::{.note}
+File set coercion does _not_ add any of the files under the coerced paths to the store.
+Only the [`toSource`](#function-library-lib.fileset.toSource) function adds files to the Nix store, and only those files contained in the `fileset` argument.
+This is in contrast to using [paths in string interpolation](https://nixos.org/manual/nix/stable/language/values.html#type-path), which does add the entire referenced path to the store.
+:::
+
+### Example {#sec-fileset-path-coercion-example}
+
+Assume we are in a local directory with a file hierarchy like this:
+```
+├─ a/
+│  ├─ x (file)
+│  └─ b/
+│     └─ y (file)
+└─ c/
+   └─ d/
+```
+
+Here's a listing of which files get included when different path expressions get coerced to file sets:
+- `./.` as a file set contains both `a/x` and `a/b/y` (`c/` does not contain any files and is therefore omitted).
+- `./a` as a file set contains both `a/x` and `a/b/y`.
+- `./a/x` as a file set contains only `a/x`.
+- `./a/b` as a file set contains only `a/b/y`.
+- `./c` as a file set is empty, since neither `c` nor `c/d` contain any files.
diff --git a/nixpkgs/doc/functions/generators.section.md b/nixpkgs/doc/functions/generators.section.md
new file mode 100644
index 000000000000..8b3ae6843a22
--- /dev/null
+++ b/nixpkgs/doc/functions/generators.section.md
@@ -0,0 +1,56 @@
+# Generators {#sec-generators}
+Generators are functions that create file formats from nix data structures, e. g. for configuration files. There are generators available for: `INI`, `JSON` and `YAML`
+
+All generators follow a similar call interface: `generatorName configFunctions data`, where `configFunctions` is an attrset of user-defined functions that format nested parts of the content. They each have common defaults, so often they do not need to be set manually. An example is `mkSectionName ? (name: libStr.escape [ "[" "]" ] name)` from the `INI` generator. It receives the name of a section and sanitizes it. The default `mkSectionName` escapes `[` and `]` with a backslash.
+
+Generators can be fine-tuned to produce exactly the file format required by your application/service. One example is an INI-file format which uses `: ` as separator, the strings `"yes"`/`"no"` as boolean values and requires all string values to be quoted:
+
+```nix
+with lib;
+let
+  customToINI = generators.toINI {
+    # specifies how to format a key/value pair
+    mkKeyValue = generators.mkKeyValueDefault {
+      # specifies the generated string for a subset of nix values
+      mkValueString = v:
+             if v == true then ''"yes"''
+        else if v == false then ''"no"''
+        else if isString v then ''"${v}"''
+        # and delegates all other values to the default generator
+        else generators.mkValueStringDefault {} v;
+    } ":";
+  };
+
+# the INI file can now be given as plain old nix values
+in customToINI {
+  main = {
+    pushinfo = true;
+    autopush = false;
+    host = "localhost";
+    port = 42;
+  };
+  mergetool = {
+    merge = "diff3";
+  };
+}
+```
+
+This will produce the following INI file as nix string:
+
+```INI
+[main]
+autopush:"no"
+host:"localhost"
+port:42
+pushinfo:"yes"
+str\:ange:"very::strange"
+
+[mergetool]
+merge:"diff3"
+```
+
+::: {.note}
+Nix store paths can be converted to strings by enclosing a derivation attribute like so: `"${drv}"`.
+:::
+
+Detailed documentation for each generator can be found in `lib/generators.nix`.
diff --git a/nixpkgs/doc/functions/library.md.in b/nixpkgs/doc/functions/library.md.in
new file mode 100644
index 000000000000..e17de86feb8a
--- /dev/null
+++ b/nixpkgs/doc/functions/library.md.in
@@ -0,0 +1,5 @@
+# Nixpkgs Library Functions {#sec-functions-library}
+
+Nixpkgs provides a standard library at `pkgs.lib`, or through `import <nixpkgs/lib>`.
+
+<!-- nixdoc-generated documentation must be appended here during build! -->
diff --git a/nixpkgs/doc/functions/library/.gitkeep b/nixpkgs/doc/functions/library/.gitkeep
new file mode 100644
index 000000000000..e69de29bb2d1
--- /dev/null
+++ b/nixpkgs/doc/functions/library/.gitkeep
diff --git a/nixpkgs/doc/functions/nix-gitignore.section.md b/nixpkgs/doc/functions/nix-gitignore.section.md
new file mode 100644
index 000000000000..8eb4081d2878
--- /dev/null
+++ b/nixpkgs/doc/functions/nix-gitignore.section.md
@@ -0,0 +1,49 @@
+# pkgs.nix-gitignore {#sec-pkgs-nix-gitignore}
+
+`pkgs.nix-gitignore` is a function that acts similarly to `builtins.filterSource` but also allows filtering with the help of the gitignore format.
+
+## Usage {#sec-pkgs-nix-gitignore-usage}
+
+`pkgs.nix-gitignore` exports a number of functions, but you'll most likely need either `gitignoreSource` or `gitignoreSourcePure`. As their first argument, they both accept either 1. a file with gitignore lines or 2. a string with gitignore lines, or 3. a list of either of the two. They will be concatenated into a single big string.
+
+```nix
+{ pkgs ? import <nixpkgs> {} }:
+
+ nix-gitignore.gitignoreSource [] ./source
+     # Simplest version
+
+ nix-gitignore.gitignoreSource "supplemental-ignores\n" ./source
+     # This one reads the ./source/.gitignore and concats the auxiliary ignores
+
+ nix-gitignore.gitignoreSourcePure "ignore-this\nignore-that\n" ./source
+     # Use this string as gitignore, don't read ./source/.gitignore.
+
+ nix-gitignore.gitignoreSourcePure ["ignore-this\nignore-that\n", ~/.gitignore] ./source
+     # It also accepts a list (of strings and paths) that will be concatenated
+     # once the paths are turned to strings via readFile.
+```
+
+These functions are derived from the `Filter` functions by setting the first filter argument to `(_: _: true)`:
+
+```nix
+gitignoreSourcePure = gitignoreFilterSourcePure (_: _: true);
+gitignoreSource = gitignoreFilterSource (_: _: true);
+```
+
+Those filter functions accept the same arguments the `builtins.filterSource` function would pass to its filters, thus `fn: gitignoreFilterSourcePure fn ""` should be extensionally equivalent to `filterSource`. The file is blacklisted if it's blacklisted by either your filter or the gitignoreFilter.
+
+If you want to make your own filter from scratch, you may use
+
+```nix
+gitignoreFilter = ign: root: filterPattern (gitignoreToPatterns ign) root;
+```
+
+## gitignore files in subdirectories {#sec-pkgs-nix-gitignore-usage-recursive}
+
+If you wish to use a filter that would search for .gitignore files in subdirectories, just like git does by default, use this function:
+
+```nix
+gitignoreFilterRecursiveSource = filter: patterns: root:
+# OR
+gitignoreRecursiveSource = gitignoreFilterSourcePure (_: _: true);
+```
diff --git a/nixpkgs/doc/functions/prefer-remote-fetch.section.md b/nixpkgs/doc/functions/prefer-remote-fetch.section.md
new file mode 100644
index 000000000000..8760c100224a
--- /dev/null
+++ b/nixpkgs/doc/functions/prefer-remote-fetch.section.md
@@ -0,0 +1,17 @@
+# prefer-remote-fetch overlay {#sec-prefer-remote-fetch}
+
+`prefer-remote-fetch` is an overlay that download sources on remote builder. This is useful when the evaluating machine has a slow upload while the builder can fetch faster directly from the source. To use it, put the following snippet as a new overlay:
+
+```nix
+self: super:
+  (super.prefer-remote-fetch self super)
+```
+
+A full configuration example for that sets the overlay up for your own account, could look like this
+
+```ShellSession
+$ mkdir ~/.config/nixpkgs/overlays/
+$ cat > ~/.config/nixpkgs/overlays/prefer-remote-fetch.nix <<EOF
+  self: super: super.prefer-remote-fetch self super
+EOF
+```