nixos/documentation: deprecate docbook option docs

following the plan in https://github.com/NixOS/nixpkgs/pull/189318#discussion_r961764451

also adds an activation script to print the warning during activation
instead of during build, otherwise folks using the new CLI that hides
build logs by default might never see the warning.

nixos/doc/manual/default.nix

@@ -209,7 +209,7 @@ let
 in rec {
   inherit generatedSources;
 
-  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook;
+  inherit (optionsDoc) optionsJSON optionsNix optionsDocBook optionsUsedDocbook;
 
   # Generate the NixOS manual.
   manualHTML = runCommand "nixos-manual-html"

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

@@ -416,6 +416,22 @@
           sudo and sources the environment variables.
         </para>
       </listitem>
+      <listitem>
+        <para>
+          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
+          <xref linkend="sec-option-declarations" /> to silence this
+          warning.
+        </para>
+        <para>
+          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.
+        </para>
+      </listitem>
       <listitem>
         <para>
           The <literal>dnsmasq</literal> service now takes configuration

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

@@ -101,6 +101,10 @@ In addition to numerous new and upgraded packages, this release has the followin
 
 - `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.
 
+- 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.
+
+  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.
+
 - The `dnsmasq` service now takes configuration via the
   `services.dnsmasq.settings` attribute set. The option
   `services.dnsmasq.extraConfig` will be deprecated when NixOS 22.11 reaches

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

@@ -139,9 +139,10 @@ in rec {
       dst=$out/share/doc/nixos
       mkdir -p $dst
 
+      TOUCH_IF_DB=$dst/.used-docbook \
       python ${./mergeJSON.py} \
         ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
-        ${lib.optionalString (! allowDocBook) "--error-on-docbook"} \
+        ${if allowDocBook then "--warn-on-docbook" else "--error-on-docbook"} \
         ${lib.optionalString markdownByDefault "--markdown-by-default"} \
         $baseJSON $options \
         > $dst/options.json
@@ -153,6 +154,14 @@ in rec {
       echo "file json-br $dst/options.json.br" >> $out/nix-support/hydra-build-products
     '';
 
+  optionsUsedDocbook = pkgs.runCommand "options-used-docbook" {} ''
+    if [ -e ${optionsJSON}/share/doc/nixos/.used-docbook ]; then
+      echo 1
+    else
+      echo 0
+    fi >"$out"
+  '';
+
   # Convert options.json into an XML file.
   # The actual generation of the xml file is done in nix purely for the convenience
   # of not having to generate the xml some other way

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

@@ -228,6 +228,7 @@ def convertMD(options: Dict[str, Any]) -> str:
     return options
 
 warningsAreErrors = False
+warnOnDocbook = False
 errorOnDocbook = False
 markdownByDefault = False
 optOffset = 0
@@ -235,7 +236,10 @@ for arg in sys.argv[1:]:
     if arg == "--warnings-are-errors":
         optOffset += 1
         warningsAreErrors = True
-    if arg == "--error-on-docbook":
+    if arg == "--warn-on-docbook":
+        optOffset += 1
+        warnOnDocbook = True
+    elif arg == "--error-on-docbook":
         optOffset += 1
         errorOnDocbook = True
     if arg == "--markdown-by-default":
@@ -278,26 +282,27 @@ def is_docbook(o, key):
 # check that every option has a description
 hasWarnings = False
 hasErrors = False
-hasDocBookErrors = False
+hasDocBook = False
 for (k, v) in options.items():
-    if errorOnDocbook:
+    if warnOnDocbook or errorOnDocbook:
+        kind = "error" if errorOnDocbook else "warning"
         if isinstance(v.value.get('description', {}), str):
-            hasErrors = True
+            hasErrors |= errorOnDocbook
-            hasDocBookErrors = True
+            hasDocBook = True
             print(
-                f"\x1b[1;31merror: option {v.name} description uses DocBook\x1b[0m",
+                f"\x1b[1;31m{kind}: option {v.name} description uses DocBook\x1b[0m",
                 file=sys.stderr)
         elif is_docbook(v.value, 'defaultText'):
-            hasErrors = True
+            hasErrors |= errorOnDocbook
-            hasDocBookErrors = True
+            hasDocBook = True
             print(
-                f"\x1b[1;31merror: option {v.name} default uses DocBook\x1b[0m",
+                f"\x1b[1;31m{kind}: option {v.name} default uses DocBook\x1b[0m",
                 file=sys.stderr)
         elif is_docbook(v.value, 'example'):
-            hasErrors = True
+            hasErrors |= errorOnDocbook
-            hasDocBookErrors = True
+            hasDocBook = True
             print(
-                f"\x1b[1;31merror: option {v.name} example uses DocBook\x1b[0m",
+                f"\x1b[1;31m{kind}: option {v.name} example uses DocBook\x1b[0m",
                 file=sys.stderr)
 
     if v.value.get('description', None) is None:
@@ -310,10 +315,14 @@ 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 hasDocBookErrors:
+if hasDocBook:
+    (why, what) = (
+        ("disallowed for in-tree modules", "contribution") if errorOnDocbook
+        else ("deprecated for option documentation", "module")
+    )
     print("Explanation: The documentation contains descriptions, examples, or defaults written in DocBook. " +
         "NixOS is in the process of migrating from DocBook to Markdown, and " +
-        "DocBook is disallowed for in-tree modules. To change your contribution to "+
+        f"DocBook is {why}. To change your {what} to "+
         "use Markdown, apply mdDoc and literalMD and use the *MD variants of option creation " +
         "functions where they are available. For example:\n" +
         "\n" +
@@ -326,6 +335,9 @@ if hasDocBookErrors:
         "  example.package = mkPackageOptionMD pkgs \"your-package\" {};\n" +
         "  imports = [ (mkAliasOptionModuleMD [ \"example\" \"args\" ] [ \"example\" \"settings\" ]) ];",
         file = sys.stderr)
+    with open(os.getenv('TOUCH_IF_DB'), 'x'):
+        # just make sure it exists
+        pass
 
 if hasErrors:
     sys.exit(1)

nixos/lib/testing/testScript.nix

@@ -7,7 +7,7 @@ in
   options = {
     testScript = mkOption {
       type = either str (functionTo str);
-      description = ''
+      description = mdDoc ''
         A series of python declarations and statements that you write to perform
         the test.
       '';

nixos/modules/misc/documentation.nix

@@ -357,6 +357,14 @@ in
     (mkIf cfg.nixos.enable {
       system.build.manual = manual;
 
+      system.activationScripts.check-manual-docbook = ''
+        if [[ $(cat ${manual.optionsUsedDocbook}) = 1 ]]; then
+          echo -e "\e[31;1mwarning\e[0m: This configuration contains option documentation in docbook." \
+                  "Support for docbook is deprecated and will be removed after NixOS 23.05." \
+                  "See nix-store --read-log ${builtins.unsafeDiscardStringContext manual.optionsJSON.drvPath}"
+        fi
+      '';
+
       environment.systemPackages = []
         ++ optional cfg.man.enable manual.manpages
         ++ optionals cfg.doc.enable [ manual.manualHTML nixos-help ];