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
type = type specification;
12
default = default value;
13
example = example value;
14
-
description = "Description for use in the NixOS manual.";
15
};
16
};
17
```
···
59
: A textual description of the option, in [Nixpkgs-flavored Markdown](
60
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be
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.
64
65
## Utility functions for common option patterns {#sec-option-declarations-util}
66
···
83
type = lib.types.bool;
84
default = false;
85
example = true;
86
-
description = "Whether to enable magic.";
87
}
88
```
89
···
116
type = lib.types.package;
117
default = pkgs.hello;
118
defaultText = lib.literalExpression "pkgs.hello";
119
-
description = "The hello package to use.";
120
}
121
```
122
···
132
default = pkgs.ghc;
133
defaultText = lib.literalExpression "pkgs.ghc";
134
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
135
-
description = "The GHC package to use.";
136
}
137
```
138
···
11
type = type specification;
12
default = default value;
13
example = example value;
14
+
description = lib.mdDoc "Description for use in the NixOS manual.";
15
};
16
};
17
```
···
59
: A textual description of the option, in [Nixpkgs-flavored Markdown](
60
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be
61
included in the NixOS manual. During the migration process from DocBook
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.
65
66
## Utility functions for common option patterns {#sec-option-declarations-util}
67
···
84
type = lib.types.bool;
85
default = false;
86
example = true;
87
+
description = lib.mdDoc "Whether to enable magic.";
88
}
89
```
90
···
117
type = lib.types.package;
118
default = pkgs.hello;
119
defaultText = lib.literalExpression "pkgs.hello";
120
+
description = lib.mdDoc "The hello package to use.";
121
}
122
```
123
···
133
default = pkgs.ghc;
134
defaultText = lib.literalExpression "pkgs.ghc";
135
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
136
+
description = lib.mdDoc "The GHC package to use.";
137
}
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
type = type specification;
13
default = default value;
14
example = example value;
15
-
description = "Description for use in the NixOS manual.";
16
};
17
};
18
</programlisting>
···
98
A textual description of the option, in
99
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
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.
104
</para>
105
</listitem>
106
</varlistentry>
···
132
type = lib.types.bool;
133
default = false;
134
example = true;
135
-
description = "Whether to enable magic.";
136
}
137
</programlisting>
138
<section xml:id="sec-option-declarations-util-mkPackageOption">
···
182
type = lib.types.package;
183
default = pkgs.hello;
184
defaultText = lib.literalExpression "pkgs.hello";
185
-
description = "The hello package to use.";
186
}
187
</programlisting>
188
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
···
197
default = pkgs.ghc;
198
defaultText = lib.literalExpression "pkgs.ghc";
199
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
200
-
description = "The GHC package to use.";
201
}
202
</programlisting>
203
<section xml:id="sec-option-declarations-eot">
···
12
type = type specification;
13
default = default value;
14
example = example value;
15
+
description = lib.mdDoc "Description for use in the NixOS manual.";
16
};
17
};
18
</programlisting>
···
98
A textual description of the option, in
99
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
100
Markdown</link> format, that will be included in the NixOS
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.
106
</para>
107
</listitem>
108
</varlistentry>
···
134
type = lib.types.bool;
135
default = false;
136
example = true;
137
+
description = lib.mdDoc "Whether to enable magic.";
138
}
139
</programlisting>
140
<section xml:id="sec-option-declarations-util-mkPackageOption">
···
184
type = lib.types.package;
185
default = pkgs.hello;
186
defaultText = lib.literalExpression "pkgs.hello";
187
+
description = lib.mdDoc "The hello package to use.";
188
}
189
</programlisting>
190
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
···
199
default = pkgs.ghc;
200
defaultText = lib.literalExpression "pkgs.ghc";
201
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
202
+
description = lib.mdDoc "The GHC package to use.";
203
}
204
</programlisting>
205
<section xml:id="sec-option-declarations-eot">