···

       
209
       
 
       
in rec {

     

       
210
       
 
       
  inherit generatedSources;

     

       
211
       
 
       


     

       
212
       
-
       
  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;

     

       
213
       
 
       


     

       
214
       
 
       
  # Generate the NixOS manual.

     

       
215
       
 
       
  manualHTML = runCommand "nixos-manual-html"

     

···

       
209
       
 
       
in rec {

     

       
210
       
 
       
  inherit generatedSources;

     

       
211
       
 
       


     

       
212
       
+
       
  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook optionsUsedDocbook;

     

       
213
       
 
       


     

       
214
       
 
       
  # Generate the NixOS manual.

     

       
215
       
 
       
  manualHTML = runCommand "nixos-manual-html"

     

···

       
418
       
 
       
      </listitem>

     

       
419
       
 
       
      <listitem>

     

       
420
       
 
       
        <para>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

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

     

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

     

       
423
       
 
       
          set. The option

     

···

       
418
       
 
       
      </listitem>

     

       
419
       
 
       
      <listitem>

     

       
420
       
 
       
        <para>

     

       
421
       
+
       
          DocBook option documentation, which has been deprecated since

     

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

     

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

     

       
424
       
+
       
          documentation as outlined in

     

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

     

       
426
       
+
       
          warning.

     

       
427
       
+
       
        </para>

     

       
428
       
+
       
        <para>

     

       
429
       
+
       
          DocBook option documentation support will be removed in the

     

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

     

       
431
       
+
       
          option documentation that has not been migrated until then

     

       
432
       
+
       
          will no longer render properly or cause errors.

     

       
433
       
+
       
        </para>

     

       
434
       
+
       
      </listitem>

     

       
435
       
+
       
      <listitem>

     

       
436
       
+
       
        <para>

     

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

     

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

     

       
439
       
 
       
          set. The option

     

···

       
101
       
 
       


     

       
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
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

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

     

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

     

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

     

···

       
101
       
 
       


     

       
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
       
 
       


     

       
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
       
+
       


     

       
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
       
+
       


     

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

     

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

     

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

     

···

       
139
       
 
       
      dst=$out/share/doc/nixos

     

       
140
       
 
       
      mkdir -p $dst

     

       
141
       
 
       


     

       
0
       
 
       

     

       
142
       
 
       
      python ${./mergeJSON.py} \

     

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

     

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

     

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

     

       
146
       
 
       
        $baseJSON $options \

     

       
147
       
 
       
        > $dst/options.json

     
···

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

     

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

     

       
154
       
 
       
    '';

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
155
       
 
       


     

       
156
       
 
       
  # Convert options.json into an XML file.

     

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

     

···

       
139
       
 
       
      dst=$out/share/doc/nixos

     

       
140
       
 
       
      mkdir -p $dst

     

       
141
       
 
       


     

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

     

       
143
       
 
       
      python ${./mergeJSON.py} \

     

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

     

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

     

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

     

       
147
       
 
       
        $baseJSON $options \

     

       
148
       
 
       
        > $dst/options.json

     
···

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

     

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

     

       
155
       
 
       
    '';

     

       
156
       
+
       


     

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

     

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

     

       
159
       
+
       
      echo 1

     

       
160
       
+
       
    else

     

       
161
       
+
       
      echo 0

     

       
162
       
+
       
    fi >"$out"

     

       
163
       
+
       
  '';

     

       
164
       
 
       


     

       
165
       
 
       
  # Convert options.json into an XML file.

     

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

     

···

       
228
       
 
       
    return options

     

       
229
       
 
       


     

       
230
       
 
       
warningsAreErrors = False

     

       
0
       
 
       

     

       
231
       
 
       
errorOnDocbook = False

     

       
232
       
 
       
markdownByDefault = False

     

       
233
       
 
       
optOffset = 0

     
···

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

     

       
236
       
 
       
        optOffset += 1

     

       
237
       
 
       
        warningsAreErrors = True

     

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

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
239
       
 
       
        optOffset += 1

     

       
240
       
 
       
        errorOnDocbook = True

     

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

     
···

       
278
       
 
       
# check that every option has a description

     

       
279
       
 
       
hasWarnings = False

     

       
280
       
 
       
hasErrors = False

     

       
281
       
-
       
hasDocBookErrors = False

     

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

     

       
283
       
-
       
    if errorOnDocbook:

     

       
0
       
 
       

     

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

     

       
285
       
-
       
            hasErrors = True

     

       
286
       
-
       
            hasDocBookErrors = True

     

       
287
       
 
       
            print(

     

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

     

       
289
       
 
       
                file=sys.stderr)

     

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

     

       
291
       
-
       
            hasErrors = True

     

       
292
       
-
       
            hasDocBookErrors = True

     

       
293
       
 
       
            print(

     

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

     

       
295
       
 
       
                file=sys.stderr)

     

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

     

       
297
       
-
       
            hasErrors = True

     

       
298
       
-
       
            hasDocBookErrors = True

     

       
299
       
 
       
            print(

     

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

     

       
301
       
 
       
                file=sys.stderr)

     

       
302
       
 
       


     

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

     
···

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

     

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

     

       
312
       
 
       


     

       
313
       
-
       
if hasDocBookErrors:

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

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

     

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

     

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

     

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

     

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

     

       
319
       
 
       
        "\n" +

     
···

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

     

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

     

       
328
       
 
       
        file = sys.stderr)

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
329
       
 
       


     

       
330
       
 
       
if hasErrors:

     

       
331
       
 
       
    sys.exit(1)

     

···

       
228
       
 
       
    return options

     

       
229
       
 
       


     

       
230
       
 
       
warningsAreErrors = False

     

       
231
       
+
       
warnOnDocbook = False

     

       
232
       
 
       
errorOnDocbook = False

     

       
233
       
 
       
markdownByDefault = False

     

       
234
       
 
       
optOffset = 0

     
···

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

     

       
237
       
 
       
        optOffset += 1

     

       
238
       
 
       
        warningsAreErrors = True

     

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

     

       
240
       
+
       
        optOffset += 1

     

       
241
       
+
       
        warnOnDocbook = True

     

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

     

       
243
       
 
       
        optOffset += 1

     

       
244
       
 
       
        errorOnDocbook = True

     

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

     
···

       
282
       
 
       
# check that every option has a description

     

       
283
       
 
       
hasWarnings = False

     

       
284
       
 
       
hasErrors = False

     

       
285
       
+
       
hasDocBook = False

     

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

     

       
287
       
+
       
    if warnOnDocbook or errorOnDocbook:

     

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

     

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

     

       
290
       
+
       
            hasErrors |= errorOnDocbook

     

       
291
       
+
       
            hasDocBook = True

     

       
292
       
 
       
            print(

     

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

     

       
294
       
 
       
                file=sys.stderr)

     

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

     

       
296
       
+
       
            hasErrors |= errorOnDocbook

     

       
297
       
+
       
            hasDocBook = True

     

       
298
       
 
       
            print(

     

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

     

       
300
       
 
       
                file=sys.stderr)

     

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

     

       
302
       
+
       
            hasErrors |= errorOnDocbook

     

       
303
       
+
       
            hasDocBook = True

     

       
304
       
 
       
            print(

     

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

     

       
306
       
 
       
                file=sys.stderr)

     

       
307
       
 
       


     

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

     
···

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

     

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

     

       
317
       
 
       


     

       
318
       
+
       
if hasDocBook:

     

       
319
       
+
       
    (why, what) = (

     

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

     

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

     

       
322
       
+
       
    )

     

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

     

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

     

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

     

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

     

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

     

       
328
       
 
       
        "\n" +

     
···

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

     

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

     

       
337
       
 
       
        file = sys.stderr)

     

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

     

       
339
       
+
       
        # just make sure it exists

     

       
340
       
+
       
        pass

     

       
341
       
 
       


     

       
342
       
 
       
if hasErrors:

     

       
343
       
 
       
    sys.exit(1)

     

···

       
7
       
 
       
  options = {

     

       
8
       
 
       
    testScript = mkOption {

     

       
9
       
 
       
      type = either str (functionTo str);

     

       
10
       
-
       
      description = ''

     

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

     

       
12
       
 
       
        the test.

     

       
13
       
 
       
      '';

     

···

       
7
       
 
       
  options = {

     

       
8
       
 
       
    testScript = mkOption {

     

       
9
       
 
       
      type = either str (functionTo str);

     

       
10
       
+
       
      description = mdDoc ''

     

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

     

       
12
       
 
       
        the test.

     

       
13
       
 
       
      '';

     

···

       
357
       
 
       
    (mkIf cfg.nixos.enable {

     

       
358
       
 
       
      system.build.manual = manual;

     

       
359
       
 
       


     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
360
       
 
       
      environment.systemPackages = []

     

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

     

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

     

···

       
357
       
 
       
    (mkIf cfg.nixos.enable {

     

       
358
       
 
       
      system.build.manual = manual;

     

       
359
       
 
       


     

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

     

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

     

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

     

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

     

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

     

       
365
       
+
       
        fi

     

       
366
       
+
       
      '';

     

       
367
       
+
       


     

       
368
       
 
       
      environment.systemPackages = []

     

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

     

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