diff options
| -rw-r--r-- | lib/options.nix | 5 | ||||
| -rw-r--r-- | nixos/doc/manual/default.nix | 3 | ||||
| -rw-r--r-- | nixos/doc/manual/development/option-declarations.section.md | 19 | ||||
| -rw-r--r-- | nixos/doc/manual/from_md/development/option-declarations.section.xml | 26 | ||||
| -rw-r--r-- | nixos/doc/manual/from_md/release-notes/rl-2211.section.xml | 19 | ||||
| -rw-r--r-- | nixos/doc/manual/release-notes/rl-2211.section.md | 4 | ||||
| -rw-r--r-- | nixos/lib/make-options-doc/default.nix | 29 | ||||
| -rw-r--r-- | nixos/lib/make-options-doc/mergeJSON.py | 39 | ||||
| -rw-r--r-- | nixos/modules/misc/documentation.nix | 19 |
9 files changed, 118 insertions, 45 deletions
diff --git a/lib/options.nix b/lib/options.nix index a56e579ab84d..dea85f0db04c 100644 --- a/lib/options.nix +++ b/lib/options.nix @@ -284,7 +284,10 @@ rec { */ literalDocBook = text: if ! isString text then throw "literalDocBook expects a string." - else { _type = "literalDocBook"; inherit text; }; + else + lib.warnIf (lib.isInOldestRelease 2211) + "literalDocBook is deprecated, use literalMD instead" + { _type = "literalDocBook"; inherit text; }; /* Transition marker for documentation that's already migrated to markdown syntax. diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 1cd769b6a544..d61bbaddf764 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 8bf73a66456b..7fdc77b964a1 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 d7c7f7716bea..ba604d109ad2 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 <literal>lib.literalExpression</literal> for a Nix expression, - <literal>lib.literalDocBook</literal> for a plain English - description in DocBook format. + <literal>lib.literalMD</literal> for a plain English + description in + <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored + Markdown</link> format. </para> </listitem> </varlistentry> @@ -82,7 +84,7 @@ options = { <para> An example value that will be shown in the NixOS manual. You can use <literal>lib.literalExpression</literal> and - <literal>lib.literalDocBook</literal> in the same way as in + <literal>lib.literalMD</literal> in the same way as in <literal>defaultText</literal>. </para> </listitem> @@ -93,18 +95,12 @@ options = { </term> <listitem> <para> - 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 - <literal>lib.mdDoc</literal> to differentiate it from DocBook. - See the nixpkgs manual for - <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">the - list of CommonMark extensions</link> supported by NixOS - documentation. - </para> - <para> - New documentation should preferably be written as CommonMark. + 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. </para> </listitem> </varlistentry> 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 9b08a5444594..ad241fa6e5a1 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 @@ -579,6 +579,25 @@ </listitem> <listitem> <para> + Option descriptions, examples, and defaults writting in + DocBook are now deprecated. Using CommonMark is preferred and + will become the default in a future release. + </para> + </listitem> + <listitem> + <para> + The + <literal>documentation.nixos.options.allowDocBook</literal> + option was added to ease the transition to CommonMark option + documentation. Setting this option to <literal>false</literal> + causes an error for every option included in the manual that + uses DocBook documentation; it defaults to + <literal>true</literal> to preserve the previous behavior and + will be removed once the transition to CommonMark is complete. + </para> + </listitem> + <listitem> + <para> The udisks2 service, available at <literal>services.udisks2.enable</literal>, is now disabled by default. It will automatically be enabled through services and diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md index 584a17cfca2c..b9ae7f5586f9 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. diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix index 3f98e2cf87b8..43dbff0e68dd 100644 --- a/nixos/lib/make-options-doc/default.nix +++ b/nixos/lib/make-options-doc/default.nix @@ -34,6 +34,10 @@ # instead of printing warnings for eg options with missing descriptions (which may be lost # by nix build unless -L is given), emit errors instead and fail the build , warningsAreErrors ? true +# allow docbook option docs if `true`. only markdown documentation is allowed when set to +# `false`, and a different renderer may be used with different bugs and performance +# characteristics but (hopefully) indistinguishable output. +, allowDocBook ? true }: let @@ -127,26 +131,23 @@ in rec { ]; options = builtins.toFile "options.json" (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix)); + # merge with an empty set if baseOptionsJSON is null to run markdown + # processing on the input options + baseJSON = + if baseOptionsJSON == null + then builtins.toFile "base.json" "{}" + else baseOptionsJSON; } '' # Export list of options in different format. dst=$out/share/doc/nixos mkdir -p $dst - ${ - if baseOptionsJSON == null - then '' - # `cp $options $dst/options.json`, but with temporary - # markdown processing - python ${./mergeJSON.py} $options <(echo '{}') > $dst/options.json - '' - else '' - python ${./mergeJSON.py} \ - ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \ - ${baseOptionsJSON} $options \ - > $dst/options.json - '' - } + python ${./mergeJSON.py} \ + ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \ + ${lib.optionalString (! allowDocBook) "--error-on-docbook"} \ + $baseJSON $options \ + > $dst/options.json brotli -9 < $dst/options.json > $dst/options.json.br diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index 1a1af11337e7..eae9ca031244 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -212,8 +212,17 @@ def convertMD(options: Dict[str, Any]) -> str: return options -warningsAreErrors = sys.argv[1] == "--warnings-are-errors" -optOffset = 1 if warningsAreErrors else 0 +warningsAreErrors = False +errorOnDocbook = False +optOffset = 0 +for arg in sys.argv[1:]: + if arg == "--warnings-are-errors": + optOffset += 1 + warningsAreErrors = True + if arg == "--error-on-docbook": + optOffset += 1 + errorOnDocbook = True + options = pivot(json.load(open(sys.argv[1 + optOffset], 'r'))) overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r'))) @@ -241,9 +250,33 @@ for (k, v) in overrides.items(): severity = "error" if warningsAreErrors else "warning" +def is_docbook(o, key): + val = o.get(key, {}) + if not isinstance(val, dict): + return False + return val.get('_type', '') == 'literalDocBook' + # check that every option has a description hasWarnings = False +hasErrors = False for (k, v) in options.items(): + if errorOnDocbook: + if isinstance(v.value.get('description', {}), str): + hasErrors = True + print( + f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m", + file=sys.stderr) + elif is_docbook(v.value, 'defaultText'): + hasErrors = True + print( + f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m", + file=sys.stderr) + elif is_docbook(v.value, 'example'): + hasErrors = True + print( + f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m", + file=sys.stderr) + if v.value.get('description', None) is None: hasWarnings = True print(f"\x1b[1;31m{severity}: option {v.name} has no description\x1b[0m", file=sys.stderr) @@ -254,6 +287,8 @@ for (k, v) in options.items(): f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " + "https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr) +if hasErrors: + sys.exit(1) if hasWarnings and warningsAreErrors: print( "\x1b[1;31m" + diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix index 5dcdc8f96c44..e85ad4efd008 100644 --- a/nixos/modules/misc/documentation.nix +++ b/nixos/modules/misc/documentation.nix @@ -99,7 +99,7 @@ let exit 1 } >&2 ''; - inherit (cfg.nixos.options) warningsAreErrors; + inherit (cfg.nixos.options) warningsAreErrors allowDocBook; }; @@ -255,6 +255,23 @@ in ''; }; + nixos.options.allowDocBook = mkOption { + type = types.bool; + default = true; + description = lib.mdDoc '' + Whether to allow DocBook option docs. When set to `false` all option using + DocBook documentation will cause a manual build error; additionally a new + renderer may be used. + + ::: {.note} + The `false` setting for this option is not yet fully supported. While it + should work fine and produce the same output as the previous toolchain + using DocBook it may not work in all circumstances. Whether markdown option + documentation is allowed is independent of this option. + ::: + ''; + }; + nixos.options.warningsAreErrors = mkOption { type = types.bool; default = true; |