gador/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #201187 from pennae/mddoc-in-manual

Browse Source 
nixos/manual: re-add mention of mdDoc marker
This commit is contained in:
Robert Hensing
2022-11-14 19:00:33 +01:00
committed by GitHub
parent 833f9d5e1f 07e5701aca
commit a82e6b5dae
2 changed files with 16 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nixos/doc/manual/development/option-declarations.section.md
+7 -6
View File
@@ -11,7 +11,7 @@ options = {
type = type specification;
default = default value;
example = example value;
description = "Description for use in the NixOS manual.";
description = lib.mdDoc "Description for use in the NixOS manual.";
};
};
```
@@ -59,8 +59,9 @@ The function `mkOption` accepts the following arguments.
: A textual description of the option, in [Nixpkgs-flavored Markdown](
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be
included in the NixOS manual. During the migration process from DocBook
to CommonMark the description may also be written in DocBook, but this is
discouraged.
it is necessary to mark descriptions written in CommonMark with `lib.mdDoc`.
The description may still be written in DocBook (without any marker), but this
is discouraged and will be deprecated in the future.
## Utility functions for common option patterns {#sec-option-declarations-util}
@@ -83,7 +84,7 @@ lib.mkOption {
type = lib.types.bool;
default = false;
example = true;
description = "Whether to enable magic.";
description = lib.mdDoc "Whether to enable magic.";
}
```
@@ -116,7 +117,7 @@ lib.mkOption {
type = lib.types.package;
default = pkgs.hello;
defaultText = lib.literalExpression "pkgs.hello";
description = "The hello package to use.";
description = lib.mdDoc "The hello package to use.";
}
```
@@ -132,7 +133,7 @@ lib.mkOption {
default = pkgs.ghc;
defaultText = lib.literalExpression "pkgs.ghc";
example = lib.literalExpression "pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])";
description = "The GHC package to use.";
description = lib.mdDoc "The GHC package to use.";
}
```
nixos/doc/manual/from_md/development/option-declarations.section.xml
+9 -7
View File
@@ -12,7 +12,7 @@ options = {
type = type specification;
default = default value;
example = example value;
description = "Description for use in the NixOS manual.";
description = lib.mdDoc "Description for use in the NixOS manual.";
};
};
</programlisting>
@@ -98,9 +98,11 @@ options = {
A textual description of the option, in
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored
Markdown</link> format, that will be included in the NixOS
manual. During the migration process from DocBook to
CommonMark the description may also be written in DocBook, but
this is discouraged.
manual. During the migration process from DocBook it is
necessary to mark descriptions written in CommonMark with
<literal>lib.mdDoc</literal>. The description may still be
written in DocBook (without any marker), but this is
discouraged and will be deprecated in the future.
</para>
</listitem>
</varlistentry>
@@ -132,7 +134,7 @@ lib.mkOption {
type = lib.types.bool;
default = false;
example = true;
description = &quot;Whether to enable magic.&quot;;
description = lib.mdDoc &quot;Whether to enable magic.&quot;;
}
</programlisting>
<section xml:id="sec-option-declarations-util-mkPackageOption">
@@ -182,7 +184,7 @@ lib.mkOption {
type = lib.types.package;
default = pkgs.hello;
defaultText = lib.literalExpression &quot;pkgs.hello&quot;;
description = &quot;The hello package to use.&quot;;
description = lib.mdDoc &quot;The hello package to use.&quot;;
}
</programlisting>
<anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" />
@@ -197,7 +199,7 @@ lib.mkOption {
default = pkgs.ghc;
defaultText = lib.literalExpression &quot;pkgs.ghc&quot;;
example = lib.literalExpression &quot;pkgs.haskell.packages.ghc92.ghc.withPackages (hkgs: [ hkgs.primes ])&quot;;
description = &quot;The GHC package to use.&quot;;
description = lib.mdDoc &quot;The GHC package to use.&quot;;
}
</programlisting>
<section xml:id="sec-option-declarations-eot">