diff options
-rw-r--r-- | nixos/doc/manual/development/meta-attributes.xml | 62 | ||||
-rw-r--r-- | nixos/doc/manual/development/writing-modules.xml | 1 |
2 files changed, 63 insertions, 0 deletions
diff --git a/nixos/doc/manual/development/meta-attributes.xml b/nixos/doc/manual/development/meta-attributes.xml new file mode 100644 index 00000000000..cebd16c2a9d --- /dev/null +++ b/nixos/doc/manual/development/meta-attributes.xml @@ -0,0 +1,62 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + 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 + <filename + xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/misc/meta.nix">meta.nix</filename> + 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> and + <literal>doc</literal>.</para> + +<para>Each of the meta-attributes must be defined at most once per module + file.</para> + +<programlisting> +{ config, lib, pkgs, ... }: +{ + options = { + ... + }; + + config = { + ... + }; + + meta = { + maintainers = with lib.maintainers; [ ericsagnes ]; <co + xml:id='modules-meta-1' /> + doc = ./default.xml; <co xml:id='modules-meta-2' /> + }; +} +</programlisting> + +<calloutlist> + <callout arearefs='modules-meta-1'> + <para> + <varname>maintainers</varname> contains a list of the module maintainers. + </para> + </callout> + + <callout arearefs='modules-meta-2'> + <para> + <varname>doc</varname> point to a valid docbook file containing the module + documentation, its contents are automatically added to the <xref + linkend="ch-configuration"/>. + Changes to a module documentation must be checked to be non-breaking by + building the NixOS manual. + </para> + <programlisting>$ nix-build nixos/release.nix -A manual</programlisting> + </callout> + +</calloutlist> + +</section> diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml index 971e586f20b..a68b122ce02 100644 --- a/nixos/doc/manual/development/writing-modules.xml +++ b/nixos/doc/manual/development/writing-modules.xml @@ -177,5 +177,6 @@ in { <xi:include href="option-declarations.xml" /> <xi:include href="option-def.xml" /> +<xi:include href="meta-attributes.xml" /> </chapter> |