dev/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

nixos/manual: fix option-declarations sections

Browse Source 
the examples for mkPackageOption weren't terminated, leading to pretty
odd nesting of docbook (and thus html) elements. close them properly.

also turn the (likewise unclosed) fenced div containing just an anchor
id and a class that will be silently dropped to an inline anchor while
we're here. we'd have to convert it anyway later.
This commit is contained in:
pennae 2023-02-08 09:57:21 +01:00
parent ba4bcdc5e4
commit 8163651338
2 changed files with 165 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
nixos/doc/manual/development/option-declarations.section.md
View File

@ -87,6 +87,7 @@ lib.mkOption {
description = lib.mdDoc "Whether to enable magic."; description = lib.mdDoc "Whether to enable magic.";
} }
``` ```
:::
### `mkPackageOption`, `mkPackageOptionMD` {#sec-option-declarations-util-mkPackageOption} ### `mkPackageOption`, `mkPackageOptionMD` {#sec-option-declarations-util-mkPackageOption}
@ -108,7 +109,7 @@ You can omit the default path if the name of the option is also attribute path i
During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed. During the transition to CommonMark documentation `mkPackageOption` creates an option with a DocBook description attribute, once the transition is completed it will create a CommonMark description instead. `mkPackageOptionMD` always creates an option with a CommonMark description attribute and will be removed some time after the transition is completed.
::: {#ex-options-declarations-util-mkPackageOption .title} []{#ex-options-declarations-util-mkPackageOption}
Examples: Examples:
::: {#ex-options-declarations-util-mkPackageOption-hello .example} ::: {#ex-options-declarations-util-mkPackageOption-hello .example}
@ -122,6 +123,7 @@ lib.mkOption {
description = lib.mdDoc "The hello package to use."; description = lib.mdDoc "The hello package to use.";
} }
``` ```
:::
::: {#ex-options-declarations-util-mkPackageOption-ghc .example} ::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
```nix ```nix
@ -138,6 +140,7 @@ lib.mkOption {
description = lib.mdDoc "The GHC package to use."; description = lib.mdDoc "The GHC package to use.";
} }
``` ```
:::
## Extensible Option Types {#sec-option-declarations-eot} ## Extensible Option Types {#sec-option-declarations-eot}

131
nixos/doc/manual/from_md/development/option-declarations.section.xml
View File

@ -137,6 +137,7 @@ lib.mkOption {
description = lib.mdDoc "Whether to enable magic."; description = lib.mdDoc "Whether to enable magic.";
} }
</programlisting> </programlisting>
</section>
<section xml:id="sec-option-declarations-util-mkPackageOption"> <section xml:id="sec-option-declarations-util-mkPackageOption">
<title><literal>mkPackageOption</literal>, <title><literal>mkPackageOption</literal>,
<literal>mkPackageOptionMD</literal></title> <literal>mkPackageOptionMD</literal></title>
@ -147,8 +148,8 @@ lib.mkOption {
mkPackageOption pkgs &quot;name&quot; { default = [ &quot;path&quot; &quot;in&quot; &quot;pkgs&quot; ]; example = &quot;literal example&quot;; } mkPackageOption pkgs &quot;name&quot; { default = [ &quot;path&quot; &quot;in&quot; &quot;pkgs&quot; ]; example = &quot;literal example&quot;; }
</programlisting> </programlisting>
<para> <para>
Creates an Option attribute set for an option that specifies Creates an Option attribute set for an option that specifies the
the package a module should use for some purpose. package a module should use for some purpose.
</para> </para>
<para> <para>
<emphasis role="strong">Note</emphasis>: You shouldn’t <emphasis role="strong">Note</emphasis>: You shouldn’t
@ -160,30 +161,30 @@ mkPackageOption pkgs &quot;name&quot; { default = [ &quot;path&quot; &quot;in&qu
</para> </para>
<para> <para>
The default package is specified as a list of strings The default package is specified as a list of strings
representing its attribute path in nixpkgs. Because of this, representing its attribute path in nixpkgs. Because of this, you
you need to pass nixpkgs itself as the first argument. need to pass nixpkgs itself as the first argument.
</para> </para>
<para> <para>
The second argument is the name of the option, used in the The second argument is the name of the option, used in the
description <quote>The &lt;name&gt; package to use.</quote>. description <quote>The &lt;name&gt; package to use.</quote>. You
You can also pass an example value, either a literal string or can also pass an example value, either a literal string or a
a package’s attribute path. package’s attribute path.
</para> </para>
<para> <para>
You can omit the default path if the name of the option is You can omit the default path if the name of the option is also
also attribute path in nixpkgs. attribute path in nixpkgs.
</para> </para>
<para> <para>
During the transition to CommonMark documentation During the transition to CommonMark documentation
<literal>mkPackageOption</literal> creates an option with a <literal>mkPackageOption</literal> creates an option with a
DocBook description attribute, once the transition is DocBook description attribute, once the transition is completed
completed it will create a CommonMark description instead. it will create a CommonMark description instead.
<literal>mkPackageOptionMD</literal> always creates an option <literal>mkPackageOptionMD</literal> always creates an option
with a CommonMark description attribute and will be removed with a CommonMark description attribute and will be removed some
some time after the transition is completed. time after the transition is completed.
</para> </para>
<anchor xml:id="ex-options-declarations-util-mkPackageOption" />
<para> <para>
<anchor xml:id="ex-options-declarations-util-mkPackageOption" />
Examples: Examples:
</para> </para>
<anchor xml:id="ex-options-declarations-util-mkPackageOption-hello" /> <anchor xml:id="ex-options-declarations-util-mkPackageOption-hello" />
@ -212,45 +213,43 @@ lib.mkOption {
description = lib.mdDoc &quot;The GHC package to use.&quot;; description = lib.mdDoc &quot;The GHC package to use.&quot;;
} }
</programlisting> </programlisting>
</section>
</section>
<section xml:id="sec-option-declarations-eot"> <section xml:id="sec-option-declarations-eot">
<title>Extensible Option Types</title> <title>Extensible Option Types</title>
<para> <para>
Extensible option types is a feature that allow to extend Extensible option types is a feature that allow to extend certain
certain types declaration through multiple module files. types declaration through multiple module files. This feature only
This feature only work with a restricted set of types, work with a restricted set of types, namely
namely <literal>enum</literal> and <literal>enum</literal> and <literal>submodules</literal> and any
<literal>submodules</literal> and any composed forms of composed forms of them.
them.
</para> </para>
<para> <para>
Extensible option types can be used for Extensible option types can be used for <literal>enum</literal>
<literal>enum</literal> options that affects multiple options that affects multiple modules, or as an alternative to
modules, or as an alternative to related related <literal>enable</literal> options.
<literal>enable</literal> options.
</para> </para>
<para> <para>
As an example, we will take the case of display managers. As an example, we will take the case of display managers. There is
There is a central display manager module for generic a central display manager module for generic display manager
display manager options and a module file per display options and a module file per display manager backend (sddm, gdm
manager backend (sddm, gdm …). …).
</para> </para>
<para> <para>
There are two approaches we could take with this module There are two approaches we could take with this module structure:
structure:
</para> </para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
Configuring the display managers independently by adding Configuring the display managers independently by adding an
an enable option to every display manager module enable option to every display manager module backend. (NixOS)
backend. (NixOS)
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
Configuring the display managers in the central module Configuring the display managers in the central module by
by adding an option to select which display manager adding an option to select which display manager backend to
backend to use. use.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -258,44 +257,43 @@ lib.mkOption {
Both approaches have problems. Both approaches have problems.
</para> </para>
<para> <para>
Making backends independent can quickly become hard to Making backends independent can quickly become hard to manage. For
manage. For display managers, there can only be one enabled display managers, there can only be one enabled at a time, but the
at a time, but the type system cannot enforce this type system cannot enforce this restriction as there is no
restriction as there is no relation between each backend’s relation between each backend’s <literal>enable</literal> option.
<literal>enable</literal> option. As a result, this As a result, this restriction has to be done explicitly by adding
restriction has to be done explicitly by adding assertions assertions in each display manager backend module.
in each display manager backend module.
</para> </para>
<para> <para>
On the other hand, managing the display manager backends in On the other hand, managing the display manager backends in the
the central module will require changing the central module central module will require changing the central module option
option every time a new backend is added or removed. every time a new backend is added or removed.
</para> </para>
<para> <para>
By using extensible option types, it is possible to create a By using extensible option types, it is possible to create a
placeholder option in the central module placeholder option in the central module
(<link linkend="ex-option-declaration-eot-service">Example: (<link linkend="ex-option-declaration-eot-service">Example:
Extensible type placeholder in the service module</link>), Extensible type placeholder in the service module</link>), and to
and to extend it in each backend module extend it in each backend module
(<link linkend="ex-option-declaration-eot-backend-gdm">Example: (<link linkend="ex-option-declaration-eot-backend-gdm">Example:
Extending Extending
<literal>services.xserver.displayManager.enable</literal> in <literal>services.xserver.displayManager.enable</literal> in the
the <literal>gdm</literal> module</link>, <literal>gdm</literal> module</link>,
<link linkend="ex-option-declaration-eot-backend-sddm">Example: <link linkend="ex-option-declaration-eot-backend-sddm">Example:
Extending Extending
<literal>services.xserver.displayManager.enable</literal> in <literal>services.xserver.displayManager.enable</literal> in the
the <literal>sddm</literal> module</link>). <literal>sddm</literal> module</link>).
</para> </para>
<para> <para>
As a result, <literal>displayManager.enable</literal> option As a result, <literal>displayManager.enable</literal> option
values can be added without changing the main service module values can be added without changing the main service module file
file and the type system automatically enforces that there and the type system automatically enforces that there can only be
can only be a single display manager enabled. a single display manager enabled.
</para> </para>
<anchor xml:id="ex-option-declaration-eot-service" /> <anchor xml:id="ex-option-declaration-eot-service" />
<para> <para>
<emphasis role="strong">Example: Extensible type placeholder <emphasis role="strong">Example: Extensible type placeholder in
in the service module</emphasis> the service module</emphasis>
</para> </para>
<programlisting language="nix"> <programlisting language="nix">
services.xserver.displayManager.enable = mkOption { services.xserver.displayManager.enable = mkOption {
@ -306,8 +304,8 @@ services.xserver.displayManager.enable = mkOption {
<anchor xml:id="ex-option-declaration-eot-backend-gdm" /> <anchor xml:id="ex-option-declaration-eot-backend-gdm" />
<para> <para>
<emphasis role="strong">Example: Extending <emphasis role="strong">Example: Extending
<literal>services.xserver.displayManager.enable</literal> in <literal>services.xserver.displayManager.enable</literal> in the
the <literal>gdm</literal> module</emphasis> <literal>gdm</literal> module</emphasis>
</para> </para>
<programlisting language="nix"> <programlisting language="nix">
services.xserver.displayManager.enable = mkOption { services.xserver.displayManager.enable = mkOption {
@ -317,8 +315,8 @@ services.xserver.displayManager.enable = mkOption {
<anchor xml:id="ex-option-declaration-eot-backend-sddm" /> <anchor xml:id="ex-option-declaration-eot-backend-sddm" />
<para> <para>
<emphasis role="strong">Example: Extending <emphasis role="strong">Example: Extending
<literal>services.xserver.displayManager.enable</literal> in <literal>services.xserver.displayManager.enable</literal> in the
the <literal>sddm</literal> module</emphasis> <literal>sddm</literal> module</emphasis>
</para> </para>
<programlisting language="nix"> <programlisting language="nix">
services.xserver.displayManager.enable = mkOption { services.xserver.displayManager.enable = mkOption {
@ -327,19 +325,16 @@ services.xserver.displayManager.enable = mkOption {
</programlisting> </programlisting>
<para> <para>
The placeholder declaration is a standard The placeholder declaration is a standard
<literal>mkOption</literal> declaration, but it is important <literal>mkOption</literal> declaration, but it is important that
that extensible option declarations only use the extensible option declarations only use the
<literal>type</literal> argument. <literal>type</literal> argument.
</para> </para>
<para> <para>
Extensible option types work with any of the composed Extensible option types work with any of the composed variants of
variants of <literal>enum</literal> such as <literal>enum</literal> such as
<literal>with types; nullOr (enum [ &quot;foo&quot; &quot;bar&quot; ])</literal> <literal>with types; nullOr (enum [ &quot;foo&quot; &quot;bar&quot; ])</literal>
or or
<literal>with types; listOf (enum [ &quot;foo&quot; &quot;bar&quot; ])</literal>. <literal>with types; listOf (enum [ &quot;foo&quot; &quot;bar&quot; ])</literal>.
</para> </para>
</section> </section>
</section> </section>
</section>
</section>
</section>