commit 767485a0dee24329e2b34cd4af0c08ea21e959ea · pyrox.dev/nixpkgs

+4 -1

lib/options.nix

···

       284
       284
        
         */

     

       285
       285
        
         literalDocBook = text:

     

       286
       286
        
           if ! isString text then throw "literalDocBook expects a string."

     

       287
       287
       -
           else { _type = "literalDocBook"; inherit text; };

     

       287
       287
       +
           else

     

       288
       288
       +
             lib.warnIf (lib.isInOldestRelease 2211)

     

       289
       289
       +
               "literalDocBook is deprecated, use literalMD instead"

     

       290
       290
       +
               { _type = "literalDocBook"; inherit text; };

     

       288
       291
        
       

     

       289
       292
        
         /* Transition marker for documentation that's already migrated to markdown

     

       290
       293
        
            syntax.

+2 -1

nixos/doc/manual/default.nix

···

       6
       6
        
       , extraSources ? []

     

       7
       7
        
       , baseOptionsJSON ? null

     

       8
       8
        
       , warningsAreErrors ? true

     

       9
       9
       +
       , allowDocBook ? true

     

       9
       10
        
       , prefix ? ../../..

     

       10
       11
        
       }:

     

       11
       12
        
       

     
···

       28
       29
        
         stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;

     

       29
       30
        
       

     

       30
       31
        
         optionsDoc = buildPackages.nixosOptionsDoc {

     

       31
       31
       -
           inherit options revision baseOptionsJSON warningsAreErrors;

     

       32
       32
       +
           inherit options revision baseOptionsJSON warningsAreErrors allowDocBook;

     

       32
       33
        
           transformOptions = opt: opt // {

     

       33
       34
        
             # Clean up declaration sites to not refer to the NixOS source tree.

     

       34
       35
        
             declarations = map stripAnyPrefixes opt.declarations;

+8 -11

nixos/doc/manual/development/option-declarations.section.md

···

       44
       44
        
       :   A textual representation of the default value to be rendered verbatim in

     

       45
       45
        
           the manual. Useful if the default value is a complex expression or depends

     

       46
       46
        
           on other values or packages.

     

       47
       47
       -
           Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for

     

       48
       48
       -
           a plain English description in DocBook format.

     

       47
       47
       +
           Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for

     

       48
       48
       +
           a plain English description in [Nixpkgs-flavored Markdown](

     

       49
       49
       +
           https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format.

     

       49
       50
        
       

     

       50
       51
        
       `example`

     

       51
       52
        
       

     

       52
       53
        
       :   An example value that will be shown in the NixOS manual.

     

       53
       53
       -
           You can use `lib.literalExpression` and `lib.literalDocBook` in the same way

     

       54
       54
       +
           You can use `lib.literalExpression` and `lib.literalMD` in the same way

     

       54
       55
        
           as in `defaultText`.

     

       55
       56
        
       

     

       56
       57
        
       `description`

     

       57
       58
        
       

     

       58
       58
       -
       :   A textual description of the option, in DocBook format, that will be

     

       59
       59
       +
       :   A textual description of the option, in [Nixpkgs-flavored Markdown](

     

       60
       60
       +
           https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format, that will be

     

       59
       61
        
           included in the NixOS manual. During the migration process from DocBook

     

       60
       60
       -
           to CommonMark the description may also be written in CommonMark, but has

     

       61
       61
       -
           to be wrapped in `lib.mdDoc` to differentiate it from DocBook. See

     

       62
       62
       -
           the nixpkgs manual for [the list of CommonMark extensions](

     

       63
       63
       -
           https://nixos.org/nixpkgs/manual/#sec-contributing-markup)

     

       64
       64
       -
           supported by NixOS documentation.

     

       65
       65
       -
       

     

       66
       66
       -
           New documentation should preferably be written as CommonMark.

     

       62
       62
       +
           to CommonMark the description may also be written in DocBook, but this is

     

       63
       63
       +
           discouraged.

     

       67
       64
        
       

     

       68
       65
        
       ## Utility functions for common option patterns {#sec-option-declarations-util}

     

       69
       66

+11 -15

nixos/doc/manual/from_md/development/option-declarations.section.xml

···

       69
       69
        
                 verbatim in the manual. Useful if the default value is a

     

       70
       70
        
                 complex expression or depends on other values or packages. Use

     

       71
       71
        
                 <literal>lib.literalExpression</literal> for a Nix expression,

     

       72
       72
       -
                 <literal>lib.literalDocBook</literal> for a plain English

     

       73
       73
       -
                 description in DocBook format.

     

       72
       72
       +
                 <literal>lib.literalMD</literal> for a plain English

     

       73
       73
       +
                 description in

     

       74
       74
       +
                 <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored

     

       75
       75
       +
                 Markdown</link> format.

     

       74
       76
        
               </para>

     

       75
       77
        
             </listitem>

     

       76
       78
        
           </varlistentry>

     
···

       82
       84
        
               <para>

     

       83
       85
        
                 An example value that will be shown in the NixOS manual. You

     

       84
       86
        
                 can use <literal>lib.literalExpression</literal> and

     

       85
       85
       -
                 <literal>lib.literalDocBook</literal> in the same way as in

     

       87
       87
       +
                 <literal>lib.literalMD</literal> in the same way as in

     

       86
       88
        
                 <literal>defaultText</literal>.

     

       87
       89
        
               </para>

     

       88
       90
        
             </listitem>

     
···

       93
       95
        
             </term>

     

       94
       96
        
             <listitem>

     

       95
       97
        
               <para>

     

       96
       96
       -
                 A textual description of the option, in DocBook format, that

     

       97
       97
       -
                 will be included in the NixOS manual. During the migration

     

       98
       98
       -
                 process from DocBook to CommonMark the description may also be

     

       99
       99
       -
                 written in CommonMark, but has to be wrapped in

     

       100
       100
       -
                 <literal>lib.mdDoc</literal> to differentiate it from DocBook.

     

       101
       101
       -
                 See the nixpkgs manual for

     

       102
       102
       -
                 <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">the

     

       103
       103
       -
                 list of CommonMark extensions</link> supported by NixOS

     

       104
       104
       -
                 documentation.

     

       105
       105
       -
               </para>

     

       106
       106
       -
               <para>

     

       107
       107
       -
                 New documentation should preferably be written as CommonMark.

     

       98
       98
       +
                 A textual description of the option, in

     

       99
       99
       +
                 <link xlink:href="https://nixos.org/nixpkgs/manual/#sec-contributing-markup">Nixpkgs-flavored

     

       100
       100
       +
                 Markdown</link> format, that will be included in the NixOS

     

       101
       101
       +
                 manual. During the migration process from DocBook to

     

       102
       102
       +
                 CommonMark the description may also be written in DocBook, but

     

       103
       103
       +
                 this is discouraged.

     

       108
       104
        
               </para>

     

       109
       105
        
             </listitem>

     

       110
       106
        
           </varlistentry>

+19

nixos/doc/manual/from_md/release-notes/rl-2211.section.xml

···

       579
       579
        
             </listitem>

     

       580
       580
        
             <listitem>

     

       581
       581
        
               <para>

     

       582
       582
       +
                 Option descriptions, examples, and defaults writting in

     

       583
       583
       +
                 DocBook are now deprecated. Using CommonMark is preferred and

     

       584
       584
       +
                 will become the default in a future release.

     

       585
       585
       +
               </para>

     

       586
       586
       +
             </listitem>

     

       587
       587
       +
             <listitem>

     

       588
       588
       +
               <para>

     

       589
       589
       +
                 The

     

       590
       590
       +
                 <literal>documentation.nixos.options.allowDocBook</literal>

     

       591
       591
       +
                 option was added to ease the transition to CommonMark option

     

       592
       592
       +
                 documentation. Setting this option to <literal>false</literal>

     

       593
       593
       +
                 causes an error for every option included in the manual that

     

       594
       594
       +
                 uses DocBook documentation; it defaults to

     

       595
       595
       +
                 <literal>true</literal> to preserve the previous behavior and

     

       596
       596
       +
                 will be removed once the transition to CommonMark is complete.

     

       597
       597
       +
               </para>

     

       598
       598
       +
             </listitem>

     

       599
       599
       +
             <listitem>

     

       600
       600
       +
               <para>

     

       582
       601
        
                 The udisks2 service, available at

     

       583
       602
        
                 <literal>services.udisks2.enable</literal>, is now disabled by

     

       584
       603
        
                 default. It will automatically be enabled through services and

+4

nixos/doc/manual/release-notes/rl-2211.section.md

···

197
197

198
198

- 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.

199
199

200
200
+
- Option descriptions, examples, and defaults writting in DocBook are now deprecated. Using CommonMark is preferred and will become the default in a future release.

201
201
+

202
202
+
- 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.

203
203
+

200
204

- 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.

201
205

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.

202
206

+15 -14

nixos/lib/make-options-doc/default.nix

···

       34
       34
        
       # instead of printing warnings for eg options with missing descriptions (which may be lost

     

       35
       35
        
       # by nix build unless -L is given), emit errors instead and fail the build

     

       36
       36
        
       , warningsAreErrors ? true

     

       37
       37
       +
       # allow docbook option docs if `true`. only markdown documentation is allowed when set to

     

       38
       38
       +
       # `false`, and a different renderer may be used with different bugs and performance

     

       39
       39
       +
       # characteristics but (hopefully) indistinguishable output.

     

       40
       40
       +
       , allowDocBook ? true

     

       37
       41
        
       }:

     

       38
       42
        
       

     

       39
       43
        
       let

     
···

       127
       131
        
             ];

     

       128
       132
        
             options = builtins.toFile "options.json"

     

       129
       133
        
               (builtins.unsafeDiscardStringContext (builtins.toJSON optionsNix));

     

       134
       134
       +
             # merge with an empty set if baseOptionsJSON is null to run markdown

     

       135
       135
       +
             # processing on the input options

     

       136
       136
       +
             baseJSON =

     

       137
       137
       +
               if baseOptionsJSON == null

     

       138
       138
       +
               then builtins.toFile "base.json" "{}"

     

       139
       139
       +
               else baseOptionsJSON;

     

       130
       140
        
           }

     

       131
       141
        
           ''

     

       132
       142
        
             # Export list of options in different format.

     

       133
       143
        
             dst=$out/share/doc/nixos

     

       134
       144
        
             mkdir -p $dst

     

       135
       145
        
       

     

       136
       136
       -
             ${

     

       137
       137
       -
               if baseOptionsJSON == null

     

       138
       138
       -
                 then ''

     

       139
       139
       -
                   # `cp $options $dst/options.json`, but with temporary

     

       140
       140
       -
                   # markdown processing

     

       141
       141
       -
                   python ${./mergeJSON.py} $options <(echo '{}') > $dst/options.json

     

       142
       142
       -
                 ''

     

       143
       143
       -
                 else ''

     

       144
       144
       -
                   python ${./mergeJSON.py} \

     

       145
       145
       -
                     ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \

     

       146
       146
       -
                     ${baseOptionsJSON} $options \

     

       147
       147
       -
                     > $dst/options.json

     

       148
       148
       -
                 ''

     

       149
       149
       -
             }

     

       146
       146
       +
             python ${./mergeJSON.py} \

     

       147
       147
       +
               ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \

     

       148
       148
       +
               ${lib.optionalString (! allowDocBook) "--error-on-docbook"} \

     

       149
       149
       +
               $baseJSON $options \

     

       150
       150
       +
               > $dst/options.json

     

       150
       151
        
       

     

       151
       152
        
             brotli -9 < $dst/options.json > $dst/options.json.br

     

       152
       153

+37 -2

nixos/lib/make-options-doc/mergeJSON.py

···

       212
       212
        
       

     

       213
       213
        
           return options

     

       214
       214
        
       

     

       215
       215
       -
       warningsAreErrors = sys.argv[1] == "--warnings-are-errors"

     

       216
       216
       -
       optOffset = 1 if warningsAreErrors else 0

     

       215
       215
       +
       warningsAreErrors = False

     

       216
       216
       +
       errorOnDocbook = False

     

       217
       217
       +
       optOffset = 0

     

       218
       218
       +
       for arg in sys.argv[1:]:

     

       219
       219
       +
           if arg == "--warnings-are-errors":

     

       220
       220
       +
               optOffset += 1

     

       221
       221
       +
               warningsAreErrors = True

     

       222
       222
       +
           if arg == "--error-on-docbook":

     

       223
       223
       +
               optOffset += 1

     

       224
       224
       +
               errorOnDocbook = True

     

       225
       225
       +
       

     

       217
       226
        
       options = pivot(json.load(open(sys.argv[1 + optOffset], 'r')))

     

       218
       227
        
       overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))

     

       219
       228
        
       

     
···

       241
       250
        
       

     

       242
       251
        
       severity = "error" if warningsAreErrors else "warning"

     

       243
       252
        
       

     

       253
       253
       +
       def is_docbook(o, key):

     

       254
       254
       +
           val = o.get(key, {})

     

       255
       255
       +
           if not isinstance(val, dict):

     

       256
       256
       +
               return False

     

       257
       257
       +
           return val.get('_type', '') == 'literalDocBook'

     

       258
       258
       +
       

     

       244
       259
        
       # check that every option has a description

     

       245
       260
        
       hasWarnings = False

     

       261
       261
       +
       hasErrors = False

     

       246
       262
        
       for (k, v) in options.items():

     

       263
       263
       +
           if errorOnDocbook:

     

       264
       264
       +
               if isinstance(v.value.get('description', {}), str):

     

       265
       265
       +
                   hasErrors = True

     

       266
       266
       +
                   print(

     

       267
       267
       +
                       f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m",

     

       268
       268
       +
                       file=sys.stderr)

     

       269
       269
       +
               elif is_docbook(v.value, 'defaultText'):

     

       270
       270
       +
                   hasErrors = True

     

       271
       271
       +
                   print(

     

       272
       272
       +
                       f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m",

     

       273
       273
       +
                       file=sys.stderr)

     

       274
       274
       +
               elif is_docbook(v.value, 'example'):

     

       275
       275
       +
                   hasErrors = True

     

       276
       276
       +
                   print(

     

       277
       277
       +
                       f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m",

     

       278
       278
       +
                       file=sys.stderr)

     

       279
       279
       +
       

     

       247
       280
        
           if v.value.get('description', None) is None:

     

       248
       281
        
               hasWarnings = True

     

       249
       282
        
               print(f"\x1b[1;31m{severity}: option {v.name} has no description\x1b[0m", file=sys.stderr)

     
···

       254
       287
        
                   f"\x1b[1;31m{severity}: option {v.name} has no type. Please specify a valid type, see " +

     

       255
       288
        
                   "https://nixos.org/manual/nixos/stable/index.html#sec-option-types\x1b[0m", file=sys.stderr)

     

       256
       289
        
       

     

       290
       290
       +
       if hasErrors:

     

       291
       291
       +
           sys.exit(1)

     

       257
       292
        
       if hasWarnings and warningsAreErrors:

     

       258
       293
        
           print(

     

       259
       294
        
               "\x1b[1;31m" +

+18 -1

nixos/modules/misc/documentation.nix

···

       99
       99
        
                     exit 1

     

       100
       100
        
                   } >&2

     

       101
       101
        
               '';

     

       102
       102
       -
           inherit (cfg.nixos.options) warningsAreErrors;

     

       102
       102
       +
           inherit (cfg.nixos.options) warningsAreErrors allowDocBook;

     

       103
       103
        
         };

     

       104
       104
        
       

     

       105
       105
        
       

     
···

       252
       252
        
                 Whether to split the option docs build into a cacheable and an uncacheable part.

     

       253
       253
        
                 Splitting the build can substantially decrease the amount of time needed to build

     

       254
       254
        
                 the manual, but some user modules may be incompatible with this splitting.

     

       255
       255
       +
               '';

     

       256
       256
       +
             };

     

       257
       257
       +
       

     

       258
       258
       +
             nixos.options.allowDocBook = mkOption {

     

       259
       259
       +
               type = types.bool;

     

       260
       260
       +
               default = true;

     

       261
       261
       +
               description = lib.mdDoc ''

     

       262
       262
       +
                 Whether to allow DocBook option docs. When set to `false` all option using

     

       263
       263
       +
                 DocBook documentation will cause a manual build error; additionally a new

     

       264
       264
       +
                 renderer may be used.

     

       265
       265
       +
       

     

       266
       266
       +
                 ::: {.note}

     

       267
       267
       +
                 The `false` setting for this option is not yet fully supported. While it

     

       268
       268
       +
                 should work fine and produce the same output as the previous toolchain

     

       269
       269
       +
                 using DocBook it may not work in all circumstances. Whether markdown option

     

       270
       270
       +
                 documentation is allowed is independent of this option.

     

       271
       271
       +
                 :::

     

       255
       272
        
               '';

     

       256
       273
        
             };

     

       257
       274