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

This commit is contained in:
Eric Sagnes 2016-08-29 16:54:25 +09:00 committed by Robin Gloster
parent da6e81ff6b
commit aa8e663b6e
2 changed files with 63 additions and 0 deletions

View file

@ -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>

View file

@ -177,5 +177,6 @@ in {
<xi:include href="option-declarations.xml" />
<xi:include href="option-def.xml" />
<xi:include href="meta-attributes.xml" />
</chapter>