lib/generators: add manual documentation

Restructures the functions reference a bit.
This commit is contained in:
Profpatsch 2016-11-17 22:29:32 +01:00
parent 26eb10e771
commit 53fc7b8272
2 changed files with 428 additions and 380 deletions

View file

@ -8,6 +8,15 @@
The nixpkgs repository has several utility functions to manipulate Nix expressions.
</para>
<section xml:id="sec-overrides">
<title>Overriding</title>
<para>
Sometimes one wants to override parts of
<literal>nixpkgs</literal>, e.g. derivation attributes, the results of
derivations or even the whole package set.
</para>
<section xml:id="sec-pkgs-overridePackages">
<title>pkgs.overridePackages</title>
@ -258,6 +267,40 @@ c = lib.makeOverridable f { a = 1; b = 2; }</programlisting>
</section>
</section>
<section xml:id="sec-generators">
<title>Generators</title>
<para>
Generators are functions that create file formats from nix
data structures, e.g. for configuration files.
There are generators available for: <literal>INI</literal>,
<literal>JSON</literal> and <literal>YAML</literal>
</para>
<para>
All generators follow a similar call interface: <code>generatorName
configFunctions data</code>, where <literal>configFunctions</literal> is a
set of user-defined functions that format variable parts of the content.
They each have common defaults, so often they do not need to be set
manually. An example is <code>mkSectionName ? (name: libStr.escape [ "[" "]"
] name)</code> from the <literal>INI</literal> generator. It gets the name
of a section and returns a sanitized name. The default
<literal>mkSectionName</literal> escapes <literal>[</literal> and
<literal>]</literal> with a backslash.
</para>
<note><para>Nix store paths can be converted to strings by enclosing a
derivation attribute like so: <code>"${drv}"</code>.</para></note>
<para>
Detailed documentation for each generator can be found in
<literal>lib/generators.nix</literal>.
</para>
</section>
<section xml:id="sec-fhs-environments">
<title>buildFHSUserEnv</title>

View file

@ -1,6 +1,11 @@
/* Functions that generate widespread config file
/* Functions that generate widespread file
* formats from nix data structures.
*
* They all follow a similar interface:
* generator { config-attrs } data
*
* Tests can be found in ./tests.nix
* Documentation in the manual, #sec-generators
*/
with import ./trivial.nix;
let