pyrox.dev
Merge pull request #201187 from pennae/mddoc-in-manual
nixos/manual: re-add mention of mdDoc marker
authored by Robert Hensing and committed by GitHub a82e6b5d 833f9d5e
+7
-6
nixos/doc/manual/development/option-declarations.section.md
+7
-6
nixos/doc/manual/development/option-declarations.section.md
···
11
11
type = type specification;
12
12
default = default value;
13
13
example = example value;
14
-
description = "Description for use in the NixOS manual.";
14
+
description = lib.mdDoc "Description for use in the NixOS manual.";
15
15
};
16
16
};
17
17
```
···
59
59
: A textual description of the option, in [Nixpkgs-flavored Markdown](
60
60
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be
61
61
included in the NixOS manual. During the migration process from DocBook
62
-
to CommonMark the description may also be written in DocBook, but this is
63
-
discouraged.
62
+
it is necessary to mark descriptions written in CommonMark with `lib.mdDoc`.
63
+
The description may still be written in DocBook (without any marker), but this
64
+
is discouraged and will be deprecated in the future.
64
65
65
66
## Utility functions for common option patterns {#sec-option-declarations-util}
66
67
···
83
84
type = lib.types.bool;
84
85
default = false;
85
86
example = true;
86
-
description = "Whether to enable magic.";
87
+
description = lib.mdDoc "Whether to enable magic.";
87
88
}
88
89
```
89
90
···
116
117
type = lib.types.package;
117
118
default = pkgs.hello;
118
119
defaultText = lib.literalExpression "pkgs.hello";
119
-
description = "The hello package to use.";
120
+
description = lib.mdDoc "The hello package to use.";
120
121
}
121
122
```
122
123
···
132
133
default = pkgs.ghc;
133
134
defaultText = lib.literalExpression "pkgs.ghc";
134
135
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
135
-
description = "The GHC package to use.";
136
+
description = lib.mdDoc "The GHC package to use.";
136
137
}
137
138
```
138
139
+9
-7
nixos/doc/manual/from_md/development/option-declarations.section.xml
+9
-7
nixos/doc/manual/from_md/development/option-declarations.section.xml
···
12
12
type = type specification;
13
13
default = default value;
14
14
example = example value;
15
-
description = "Description for use in the NixOS manual.";
15
+
description = lib.mdDoc "Description for use in the NixOS manual.";
16
16
};
17
17
};
18
18
</programlisting>
···
98
98
A textual description of the option, in
99
99
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
100
100
Markdown</link> format, that will be included in the NixOS
101
-
manual. During the migration process from DocBook to
102
-
CommonMark the description may also be written in DocBook, but
103
-
this is discouraged.
101
+
manual. During the migration process from DocBook it is
102
+
necessary to mark descriptions written in CommonMark with
103
+
<literal>lib.mdDoc</literal>. The description may still be
104
+
written in DocBook (without any marker), but this is
105
+
discouraged and will be deprecated in the future.
104
106
</para>
105
107
</listitem>
106
108
</varlistentry>
···
132
134
type = lib.types.bool;
133
135
default = false;
134
136
example = true;
135
-
description = "Whether to enable magic.";
137
+
description = lib.mdDoc "Whether to enable magic.";
136
138
}
137
139
</programlisting>
138
140
<section xml:id="sec-option-declarations-util-mkPackageOption">
···
182
184
type = lib.types.package;
183
185
default = pkgs.hello;
184
186
defaultText = lib.literalExpression "pkgs.hello";
185
-
description = "The hello package to use.";
187
+
description = lib.mdDoc "The hello package to use.";
186
188
}
187
189
</programlisting>
188
190
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
···
197
199
default = pkgs.ghc;
198
200
defaultText = lib.literalExpression "pkgs.ghc";
199
201
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
200
-
description = "The GHC package to use.";
202
+
description = lib.mdDoc "The GHC package to use.";
201
203
}
202
204
</programlisting>
203
205
<section xml:id="sec-option-declarations-eot">