blob: 1eb6e0f303682c510e742a73d8379fdf063d9126 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-meta-attributes">
<title>Meta Attributes</title>
<para>
Like Nix packages, NixOS modules can declare meta-attributes to
provide extra information. Module meta attributes are defined in the
<literal>meta.nix</literal> special module.
</para>
<para>
<literal>meta</literal> is a top level attribute like
<literal>options</literal> and <literal>config</literal>. Available
meta-attributes are <literal>maintainers</literal>,
<literal>doc</literal>, and <literal>buildDocsInSandbox</literal>.
</para>
<para>
Each of the meta-attributes must be defined at most once per module
file.
</para>
<programlisting language="bash">
{ config, lib, pkgs, ... }:
{
options = {
...
};
config = {
...
};
meta = {
maintainers = with lib.maintainers; [ ericsagnes ];
doc = ./default.xml;
buildDocsInSandbox = true;
};
}
</programlisting>
<itemizedlist>
<listitem>
<para>
<literal>maintainers</literal> contains a list of the module
maintainers.
</para>
</listitem>
<listitem>
<para>
<literal>doc</literal> points to a valid DocBook file containing
the module documentation. Its contents is automatically added to
<xref linkend="ch-configuration" />. Changes to a module
documentation have to be checked to not break building the NixOS
manual:
</para>
<programlisting>
$ nix-build nixos/release.nix -A manual.x86_64-linux
</programlisting>
</listitem>
<listitem>
<para>
<literal>buildDocsInSandbox</literal> indicates whether the
option documentation for the module can be built in a derivation
sandbox. This option is currently only honored for modules
shipped by nixpkgs. User modules and modules taken from
<literal>NIXOS_EXTRA_MODULE_PATH</literal> are always built
outside of the sandbox, as has been the case in previous
releases.
</para>
<para>
Building NixOS option documentation in a sandbox allows caching
of the built documentation, which greatly decreases the amount
of time needed to evaluate a system configuration that has NixOS
documentation enabled. The sandbox also restricts which
attributes may be referenced by documentation attributes (such
as option descriptions) to the <literal>options</literal> and
<literal>lib</literal> module arguments and the
<literal>pkgs.formats</literal> attribute of the
<literal>pkgs</literal> argument, <literal>config</literal> and
the rest of <literal>pkgs</literal> are disallowed and will
cause doc build failures when used. This restriction is
necessary because we cannot reproduce the full nixpkgs
instantiation with configuration and overlays from a system
configuration inside the sandbox. The <literal>options</literal>
argument only includes options of modules that are also built
inside the sandbox, referencing an option of a module that isn’t
built in the sandbox is also forbidden.
</para>
<para>
The default is <literal>true</literal> and should usually not be
changed; set it to <literal>false</literal> only if the module
requires access to <literal>pkgs</literal> in its documentation
(e.g. because it loads information from a linked package to
build an option type) or if its documentation depends on other
modules that also aren’t sandboxed (e.g. by using types defined
in the other module).
</para>
</listitem>
</itemizedlist>
</section>
|