diff options
-rw-r--r-- | nixos/doc/manual/development/option-declarations.section.md | 13 | ||||
-rw-r--r-- | nixos/doc/manual/from_md/development/option-declarations.section.xml | 16 |
2 files changed, 16 insertions, 13 deletions
diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md index 0f5673dd4d585..88617ab1920a9 100644 --- a/nixos/doc/manual/development/option-declarations.section.md +++ b/nixos/doc/manual/development/option-declarations.section.md @@ -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."; } ``` diff --git a/nixos/doc/manual/from_md/development/option-declarations.section.xml b/nixos/doc/manual/from_md/development/option-declarations.section.xml index 69163853b6279..0932a51a18cdb 100644 --- a/nixos/doc/manual/from_md/development/option-declarations.section.xml +++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml @@ -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 = "Whether to enable magic."; + description = lib.mdDoc "Whether to enable magic."; } </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 "pkgs.hello"; - description = "The hello package to use."; + description = lib.mdDoc "The hello package to use."; } </programlisting> <anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" /> @@ -197,7 +199,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."; } </programlisting> <section xml:id="sec-option-declarations-eot"> |