nixos doc: add modules meta-attributes (#18078)

1 files changed, 62 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>