commit df09c21fb262ed07f01099625ef9310a8a8392ae · pyrox.dev/nixpkgs

+1 -1

nixos/doc/manual/default.nix

···

       209
       209
        
       in rec {

     

       210
       210
        
         inherit generatedSources;

     

       211
       211
        
       

     

       212
       212
       -
         inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;

     

       212
       212
       +
         inherit (optionsDoc) optionsJSON optionsNix optionsDocBook optionsUsedDocbook;

     

       213
       213
        
       

     

       214
       214
        
         # Generate the NixOS manual.

     

       215
       215
        
         manualHTML = runCommand "nixos-manual-html"

+16

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

···

       418
       418
        
             </listitem>

     

       419
       419
        
             <listitem>

     

       420
       420
        
               <para>

     

       421
       421
       +
                 DocBook option documentation, which has been deprecated since

     

       422
       422
       +
                 22.11, will now cause a warning when documentation is built.

     

       423
       423
       +
                 Out-of-tree modules should migrate to using CommonMark

     

       424
       424
       +
                 documentation as outlined in

     

       425
       425
       +
                 <xref linkend="sec-option-declarations" /> to silence this

     

       426
       426
       +
                 warning.

     

       427
       427
       +
               </para>

     

       428
       428
       +
               <para>

     

       429
       429
       +
                 DocBook option documentation support will be removed in the

     

       430
       430
       +
                 next release and CommonMark will become the default. DocBook

     

       431
       431
       +
                 option documentation that has not been migrated until then

     

       432
       432
       +
                 will no longer render properly or cause errors.

     

       433
       433
       +
               </para>

     

       434
       434
       +
             </listitem>

     

       435
       435
       +
             <listitem>

     

       436
       436
       +
               <para>

     

       421
       437
        
                 The <literal>dnsmasq</literal> service now takes configuration

     

       422
       438
        
                 via the <literal>services.dnsmasq.settings</literal> attribute

     

       423
       439
        
                 set. The option

+4

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

···

       101
       101
        
       

     

       102
       102
        
       - `services.mastodon` gained a tootctl wrapped named `mastodon-tootctl` similar to `nextcloud-occ` which can be executed from any user and switches to the configured mastodon user with sudo and sources the environment variables.

     

       103
       103
        
       

     

       104
       104
       +
       - DocBook option documentation, which has been deprecated since 22.11, will now cause a warning when documentation is built. Out-of-tree modules should migrate to using CommonMark documentation as outlined in [](#sec-option-declarations) to silence this warning.

     

       105
       105
       +
       

     

       106
       106
       +
         DocBook option documentation support will be removed in the next release and CommonMark will become the default. DocBook option documentation that has not been migrated until then will no longer render properly or cause errors.

     

       107
       107
       +
       

     

       104
       108
        
       - The `dnsmasq` service now takes configuration via the

     

       105
       109
        
         `services.dnsmasq.settings` attribute set. The option

     

       106
       110
        
         `services.dnsmasq.extraConfig` will be deprecated when NixOS 22.11 reaches

+10 -1

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

···

       139
       139
        
             dst=$out/share/doc/nixos

     

       140
       140
        
             mkdir -p $dst

     

       141
       141
        
       

     

       142
       142
       +
             TOUCH_IF_DB=$dst/.used-docbook \

     

       142
       143
        
             python ${./mergeJSON.py} \

     

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

     

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

     

       145
       145
       +
               ${if allowDocBook then "--warn-on-docbook" else "--error-on-docbook"} \

     

       145
       146
        
               ${lib.optionalString markdownByDefault "--markdown-by-default"} \

     

       146
       147
        
               $baseJSON $options \

     

       147
       148
        
               > $dst/options.json

     
···

       152
       153
        
             echo "file json $dst/options.json" >> $out/nix-support/hydra-build-products

     

       153
       154
        
             echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products

     

       154
       155
        
           '';

     

       156
       156
       +
       

     

       157
       157
       +
         optionsUsedDocbook = pkgs.runCommand "options-used-docbook" {} ''

     

       158
       158
       +
           if [ -e ${optionsJSON}/share/doc/nixos/.used-docbook ]; then

     

       159
       159
       +
             echo 1

     

       160
       160
       +
           else

     

       161
       161
       +
             echo 0

     

       162
       162
       +
           fi >"$out"

     

       163
       163
       +
         '';

     

       155
       164
        
       

     

       156
       165
        
         # Convert options.json into an XML file.

     

       157
       166
        
         # The actual generation of the xml file is done in nix purely for the convenience

+26 -14

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

···

       228
       228
        
           return options

     

       229
       229
        
       

     

       230
       230
        
       warningsAreErrors = False

     

       231
       231
       +
       warnOnDocbook = False

     

       231
       232
        
       errorOnDocbook = False

     

       232
       233
        
       markdownByDefault = False

     

       233
       234
        
       optOffset = 0

     
···

       235
       236
        
           if arg == "--warnings-are-errors":

     

       236
       237
        
               optOffset += 1

     

       237
       238
        
               warningsAreErrors = True

     

       238
       238
       -
           if arg == "--error-on-docbook":

     

       239
       239
       +
           if arg == "--warn-on-docbook":

     

       240
       240
       +
               optOffset += 1

     

       241
       241
       +
               warnOnDocbook = True

     

       242
       242
       +
           elif arg == "--error-on-docbook":

     

       239
       243
        
               optOffset += 1

     

       240
       244
        
               errorOnDocbook = True

     

       241
       245
        
           if arg == "--markdown-by-default":

     
···

       278
       282
        
       # check that every option has a description

     

       279
       283
        
       hasWarnings = False

     

       280
       284
        
       hasErrors = False

     

       281
       281
       -
       hasDocBookErrors = False

     

       285
       285
       +
       hasDocBook = False

     

       282
       286
        
       for (k, v) in options.items():

     

       283
       283
       -
           if errorOnDocbook:

     

       287
       287
       +
           if warnOnDocbook or errorOnDocbook:

     

       288
       288
       +
               kind = "error" if errorOnDocbook else "warning"

     

       284
       289
        
               if isinstance(v.value.get('description', {}), str):

     

       285
       285
       -
                   hasErrors = True

     

       286
       286
       -
                   hasDocBookErrors = True

     

       290
       290
       +
                   hasErrors |= errorOnDocbook

     

       291
       291
       +
                   hasDocBook = True

     

       287
       292
        
                   print(

     

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

     

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

     

       289
       294
        
                       file=sys.stderr)

     

       290
       295
        
               elif is_docbook(v.value, 'defaultText'):

     

       291
       291
       -
                   hasErrors = True

     

       292
       292
       -
                   hasDocBookErrors = True

     

       296
       296
       +
                   hasErrors |= errorOnDocbook

     

       297
       297
       +
                   hasDocBook = True

     

       293
       298
        
                   print(

     

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

     

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

     

       295
       300
        
                       file=sys.stderr)

     

       296
       301
        
               elif is_docbook(v.value, 'example'):

     

       297
       297
       -
                   hasErrors = True

     

       298
       298
       -
                   hasDocBookErrors = True

     

       302
       302
       +
                   hasErrors |= errorOnDocbook

     

       303
       303
       +
                   hasDocBook = True

     

       299
       304
        
                   print(

     

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

     

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

     

       301
       306
        
                       file=sys.stderr)

     

       302
       307
        
       

     

       303
       308
        
           if v.value.get('description', None) is None:

     
···

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

     

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

     

       312
       317
        
       

     

       313
       313
       -
       if hasDocBookErrors:

     

       318
       318
       +
       if hasDocBook:

     

       319
       319
       +
           (why, what) = (

     

       320
       320
       +
               ("disallowed for in-tree modules", "contribution") if errorOnDocbook

     

       321
       321
       +
               else ("deprecated for option documentation", "module")

     

       322
       322
       +
           )

     

       314
       323
        
           print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " +

     

       315
       324
        
               "NixOS is in the process of migrating from DocBook to Markdown, and " +

     

       316
       316
       -
               "DocBook is disallowed for in-tree modules. To change your contribution to "+

     

       325
       325
       +
               f"DocBook is {why}. To change your {what} to "+

     

       317
       326
        
               "use Markdown, apply mdDoc and literalMD and use the *MD variants of option creation " +

     

       318
       327
        
               "functions where they are available. For example:\n" +

     

       319
       328
        
               "\n" +

     
···

       326
       335
        
               "  example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" +

     

       327
       336
        
               "  imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];",

     

       328
       337
        
               file = sys.stderr)

     

       338
       338
       +
           with open(os.getenv('TOUCH_IF_DB'), 'x'):

     

       339
       339
       +
               # just make sure it exists

     

       340
       340
       +
               pass

     

       329
       341
        
       

     

       330
       342
        
       if hasErrors:

     

       331
       343
        
           sys.exit(1)

+1 -1

nixos/lib/testing/testScript.nix

···

       7
       7
        
         options = {

     

       8
       8
        
           testScript = mkOption {

     

       9
       9
        
             type = either str (functionTo str);

     

       10
       10
       -
             description = ''

     

       10
       10
       +
             description = mdDoc ''

     

       11
       11
        
               A series of python declarations and statements that you write to perform

     

       12
       12
        
               the test.

     

       13
       13
        
             '';

+8

nixos/modules/misc/documentation.nix

···

       357
       357
        
           (mkIf cfg.nixos.enable {

     

       358
       358
        
             system.build.manual = manual;

     

       359
       359
        
       

     

       360
       360
       +
             system.activationScripts.check-manual-docbook = ''

     

       361
       361
       +
               if [[ $(cat ${manual.optionsUsedDocbook}) = 1 ]]; then

     

       362
       362
       +
                 echo -e "\e[31;1mwarning\e[0m: This configuration contains option documentation in docbook." \

     

       363
       363
       +
                         "Support for docbook is deprecated and will be removed after NixOS 23.05." \

     

       364
       364
       +
                         "See nix-store --read-log ${builtins.unsafeDiscardStringContext manual.optionsJSON.drvPath}"

     

       365
       365
       +
               fi

     

       366
       366
       +
             '';

     

       367
       367
       +
       

     

       360
       368
        
             environment.systemPackages = []

     

       361
       369
        
               ++ optional cfg.man.enable manual.manpages

     

       362
       370
        
               ++ optionals cfg.doc.enable [ manual.manualHTML nixos-help ];