From 767485a0dee24329e2b34cd4af0c08ea21e959ea Mon Sep 17 00:00:00 2001 From: pennae Date: Thu, 1 Sep 2022 19:23:59 +0200 Subject: lib/options: deprecate docbook text and literalDocBook deprecate literalDocBook by adding a warning (that will not fire yet) to its uses and other docbook literal strings by adding optional warning message to mergeJSON. --- nixos/doc/manual/default.nix | 3 ++- .../development/option-declarations.section.md | 19 +++++++--------- .../development/option-declarations.section.xml | 26 +++++++++------------- .../from_md/release-notes/rl-2211.section.xml | 19 ++++++++++++++++ nixos/doc/manual/release-notes/rl-2211.section.md | 4 ++++ 5 files changed, 44 insertions(+), 27 deletions(-) (limited to 'nixos/doc/manual') diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 1cd769b6a544d..d61bbaddf764d 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -6,6 +6,7 @@ , extraSources ? [] , baseOptionsJSON ? null , warningsAreErrors ? true +, allowDocBook ? true , prefix ? ../../.. }: @@ -28,7 +29,7 @@ let stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip; optionsDoc = buildPackages.nixosOptionsDoc { - inherit options revision baseOptionsJSON warningsAreErrors; + inherit options revision baseOptionsJSON warningsAreErrors allowDocBook; transformOptions = opt: opt // { # Clean up declaration sites to not refer to the NixOS source tree. declarations = map stripAnyPrefixes opt.declarations; diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md index 8bf73a66456ba..7fdc77b964a17 100644 --- a/nixos/doc/manual/development/option-declarations.section.md +++ b/nixos/doc/manual/development/option-declarations.section.md @@ -44,26 +44,23 @@ The function `mkOption` accepts the following arguments. : A textual representation of the default value to be rendered verbatim in the manual. Useful if the default value is a complex expression or depends on other values or packages. - Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for - a plain English description in DocBook format. + Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for + a plain English description in [Nixpkgs-flavored Markdown]( + https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format. `example` : An example value that will be shown in the NixOS manual. - You can use `lib.literalExpression` and `lib.literalDocBook` in the same way + You can use `lib.literalExpression` and `lib.literalMD` in the same way as in `defaultText`. `description` -: A textual description of the option, in DocBook format, that will be +: 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 CommonMark, but has - to be wrapped in `lib.mdDoc` to differentiate it from DocBook. See - the nixpkgs manual for [the list of CommonMark extensions]( - https://nixos.org/nixpkgs/manual/#sec-contributing-markup) - supported by NixOS documentation. - - New documentation should preferably be written as CommonMark. + to CommonMark the description may also be written in DocBook, but this is + discouraged. ## Utility functions for common option patterns {#sec-option-declarations-util} 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 d7c7f7716bead..ba604d109ad2a 100644 --- a/nixos/doc/manual/from_md/development/option-declarations.section.xml +++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml @@ -69,8 +69,10 @@ options = { verbatim in the manual. Useful if the default value is a complex expression or depends on other values or packages. Use lib.literalExpression for a Nix expression, - lib.literalDocBook for a plain English - description in DocBook format. + lib.literalMD for a plain English + description in + Nixpkgs-flavored + Markdown format. @@ -82,7 +84,7 @@ options = { An example value that will be shown in the NixOS manual. You can use lib.literalExpression and - lib.literalDocBook in the same way as in + lib.literalMD in the same way as in defaultText. @@ -93,18 +95,12 @@ options = { - A textual description of the option, in DocBook format, that - will be included in the NixOS manual. During the migration - process from DocBook to CommonMark the description may also be - written in CommonMark, but has to be wrapped in - lib.mdDoc to differentiate it from DocBook. - See the nixpkgs manual for - the - list of CommonMark extensions supported by NixOS - documentation. - - - New documentation should preferably be written as CommonMark. + A textual description of the option, in + Nixpkgs-flavored + Markdown 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. diff --git a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml index 9b08a5444594f..ad241fa6e5a14 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml @@ -577,6 +577,25 @@ as coreboot’s fork is no longer available. + + + Option descriptions, examples, and defaults writting in + DocBook are now deprecated. Using CommonMark is preferred and + will become the default in a future release. + + + + + The + documentation.nixos.options.allowDocBook + option was added to ease the transition to CommonMark option + documentation. Setting this option to false + causes an error for every option included in the manual that + uses DocBook documentation; it defaults to + true to preserve the previous behavior and + will be removed once the transition to CommonMark is complete. + + The udisks2 service, available at diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md index 584a17cfca2cc..b9ae7f5586f97 100644 --- a/nixos/doc/manual/release-notes/rl-2211.section.md +++ b/nixos/doc/manual/release-notes/rl-2211.section.md @@ -197,6 +197,10 @@ Use `configure.packages` instead. - memtest86+ was updated from 5.00-coreboot-002 to 6.00-beta2. It is now the upstream version from https://www.memtest.org/, as coreboot's fork is no longer available. +- Option descriptions, examples, and defaults writting in DocBook are now deprecated. Using CommonMark is preferred and will become the default in a future release. + +- The `documentation.nixos.options.allowDocBook` option was added to ease the transition to CommonMark option documentation. Setting this option to `false` causes an error for every option included in the manual that uses DocBook documentation; it defaults to `true` to preserve the previous behavior and will be removed once the transition to CommonMark is complete. + - The udisks2 service, available at `services.udisks2.enable`, is now disabled by default. It will automatically be enabled through services and desktop environments as needed. This also means that polkit will now actually be disabled by default. The default for `security.polkit.enable` was already flipped in the previous release, but udisks2 being enabled by default re-enabled it. -- cgit 1.4.1