From aa8e663b6e6f6e0c47000ab509cbe7e0f35a8aad Mon Sep 17 00:00:00 2001
From: Eric Sagnes <eric.sagnes@gmail.com>
Date: Mon, 29 Aug 2016 16:54:25 +0900
Subject: nixos doc: add modules meta-attributes (#18078)

---
 nixos/doc/manual/development/meta-attributes.xml | 62 ++++++++++++++++++++++++
 nixos/doc/manual/development/writing-modules.xml |  1 +
 2 files changed, 63 insertions(+)
 create mode 100644 nixos/doc/manual/development/meta-attributes.xml

(limited to 'nixos/doc/manual/development')

diff --git a/nixos/doc/manual/development/meta-attributes.xml b/nixos/doc/manual/development/meta-attributes.xml
new file mode 100644
index 000000000000..cebd16c2a9d0
--- /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 971e586f20bd..a68b122ce022 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>
-- 
cgit 1.4.1