diff options
Diffstat (limited to 'nixos/doc/manual/from_md/development/meta-attributes.section.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/development/meta-attributes.section.xml | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml new file mode 100644 index 00000000000..1eb6e0f3036 --- /dev/null +++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml @@ -0,0 +1,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> |