mirror of
https://github.com/NixOS/nixpkgs.git
synced 2025-06-10 03:23:29 +03:00
0a6e6cf7e6
this converts meta.doc into an md pointer, not an xml pointer. since we no longer need xml for manual chapters we can also remove support for manual chapters from md-to-db.sh since pandoc converts smart quotes to docbook quote elements and our nixos-render-docs does not we lose this distinction in the rendered output. that's probably not that bad, our stylesheet didn't make use of this anyway (and pre-23.05 versions of the chapters didn't use quote elements either). also updates the nixpkgs manual to clarify that option docs support all extensions (although it doesn't support headings at all, so heading anchors don't work by extension).
97 lines
3.8 KiB
XML
97 lines
3.8 KiB
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.md;
|
||
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
|
||
<link xlink:href="https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup">Nixpkgs-flavored
|
||
CommonMark</link> 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>
|