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.

7 files changed, 66 insertions, 17 deletions

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 9b72e840f4b10..a89e5e466500b 100644
--- a/nixos/doc/manual/default.nix
+++ b/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"
diff --git a/nixos/doc/manual/from_md/release-notes/rl-2305.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2305.section.xml
index d5afcac8556d0..17769ff0b45bc 100644
--- a/nixos/doc/manual/from_md/release-notes/rl-2305.section.xml
+++ b/nixos/doc/manual/from_md/release-notes/rl-2305.section.xml
@@ -418,6 +418,22 @@
       </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
           via the <literal>services.dnsmasq.settings</literal> attribute
           set. The option
diff --git a/nixos/doc/manual/release-notes/rl-2305.section.md b/nixos/doc/manual/release-notes/rl-2305.section.md
index 74e048beb245e..d4b31a9df1b8e 100644
--- a/nixos/doc/manual/release-notes/rl-2305.section.md
+++ b/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
diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix
index e2ed7bb71885b..7595b66771a58 100644
--- a/nixos/lib/make-options-doc/default.nix
+++ b/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
diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py
index c4f490fc2ad87..3108b9e2197fa 100644
--- a/nixos/lib/make-options-doc/mergeJSON.py
+++ b/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
-            hasDocBookErrors = True
+            hasErrors |= errorOnDocbook
+            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
-            hasDocBookErrors = True
+            hasErrors |= errorOnDocbook
+            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
-            hasDocBookErrors = True
+            hasErrors |= errorOnDocbook
+            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)
diff --git a/nixos/lib/testing/testScript.nix b/nixos/lib/testing/testScript.nix
index 5d4181c5f5dd5..5c36d754d79d7 100644
--- a/nixos/lib/testing/testScript.nix
+++ b/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.
       '';
diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix
index e44a9899772f1..ecc40ad6adef7 100644
--- a/nixos/modules/misc/documentation.nix
+++ b/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 ];