nixpkgs/nixos/doc/manual/from_md/development/meta-attributes.section.xml

<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="nix">
{ 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>
      <para>
        This file should <emphasis>not</emphasis> usually be written by
        hand. Instead it is preferred to write documentation using
        CommonMark and converting it to CommonMark using pandoc. The
        simplest documentation can be converted using just
      </para>
      <programlisting>
$ pandoc doc.md -t docbook --top-level-division=chapter -f markdown+smart &gt; doc.xml
</programlisting>
      <para>
        More elaborate documentation may wish to add one or more of the
        pandoc filters used to build the remainder of the manual, for
        example the GNOME desktop uses
      </para>
      <programlisting>
$ pandoc gnome.md -t docbook --top-level-division=chapter \
    --extract-media=media -f markdown+smart \
    --lua-filter ../../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua \
    --lua-filter ../../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua \
    &gt; gnome.xml
</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>