From 50954ad1c5847e04fe78fa155fed97ee52dcb9f6 Mon Sep 17 00:00:00 2001
From: pennae <github@quasiparticle.net>
Date: Sat, 18 Dec 2021 19:37:41 +0100
Subject: [PATCH] nixos/make-options-doc: treat missing descriptions as errors
 by default

this partially solves the problem of "missing description" warnings of the
options doc build being lost by nix build, at the cost of failing builds that
previously ran. an option to disable this behaviour is provided.
---
 nixos/doc/manual/default.nix            | 13 +++++++++++--
 nixos/lib/make-options-doc/default.nix  |  4 ++++
 nixos/lib/make-options-doc/mergeJSON.py | 20 ++++++++++++++++----
 nixos/modules/misc/documentation.nix    | 14 ++++++++++++--
 4 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 9bc63686fa3a..52d500c64d33 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -1,4 +1,13 @@
-{ pkgs, options, config, version, revision, extraSources ? [], baseOptionsJSON ? null, prefix ? ../../.. }:
+{ pkgs
+, options
+, config
+, version
+, revision
+, extraSources ? []
+, baseOptionsJSON ? null
+, warningsAreErrors ? true
+, prefix ? ../../..
+}:
 
 with pkgs;
 
@@ -15,7 +24,7 @@ let
   stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip;
 
   optionsDoc = buildPackages.nixosOptionsDoc {
-    inherit options revision baseOptionsJSON;
+    inherit options revision baseOptionsJSON warningsAreErrors;
     transformOptions = opt: opt // {
       # Clean up declaration sites to not refer to the NixOS source tree.
       declarations = map stripAnyPrefixes opt.declarations;
diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix
index cc4ddd55d026..57652dd5db1e 100644
--- a/nixos/lib/make-options-doc/default.nix
+++ b/nixos/lib/make-options-doc/default.nix
@@ -25,6 +25,9 @@
 # used to split the options doc build into a static part (nixos/modules) and a dynamic part
 # (non-nixos modules imported via configuration.nix, other module sources).
 , baseOptionsJSON ? null
+# instead of printing warnings for eg options with missing descriptions (which may be lost
+# by nix build unless -L is given), emit errors instead and fail the build
+, warningsAreErrors ? true
 }:
 
 let
@@ -121,6 +124,7 @@ in rec {
           then "cp $options $dst/options.json"
           else ''
             ${pkgs.python3Minimal}/bin/python ${./mergeJSON.py} \
+              ${lib.optionalString warningsAreErrors "--warnings-are-errors"} \
               ${baseOptionsJSON} $options \
               > $dst/options.json
           ''
diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py
index b7dfe2b88e7a..029787a31586 100644
--- a/nixos/lib/make-options-doc/mergeJSON.py
+++ b/nixos/lib/make-options-doc/mergeJSON.py
@@ -41,8 +41,10 @@ def unpivot(options: Dict[Key, Option]) -> Dict[str, JSON]:
         result[opt.name] = opt.value
     return result
 
-options = pivot(json.load(open(sys.argv[1], 'r')))
-overrides = pivot(json.load(open(sys.argv[2], 'r')))
+warningsAreErrors = sys.argv[1] == "--warnings-are-errors"
+optOffset = 1 if warningsAreErrors else 0
+options = pivot(json.load(open(sys.argv[1 + optOffset], 'r')))
+overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r')))
 
 # fix up declaration paths in lazy options, since we don't eval them from a full nixpkgs dir
 for (k, v) in options.items():
@@ -65,10 +67,20 @@ for (k, v) in overrides.items():
             cur[ok] = ov
 
 # check that every option has a description
-# TODO: nixos-rebuild with flakes may hide the warning, maybe turn on -L by default for those?
+hasWarnings = False
 for (k, v) in options.items():
     if v.value.get('description', None) is None:
-        print(f"\x1b[1;31mwarning: option {v.name} has no description\x1b[0m", file=sys.stderr)
+        severity = "error" if warningsAreErrors else "warning"
+        hasWarnings = True
+        print(f"\x1b[1;31m{severity}: option {v.name} has no description\x1b[0m", file=sys.stderr)
         v.value['description'] = "This option has no description."
+if hasWarnings and warningsAreErrors:
+    print(
+        "\x1b[1;31m" +
+        "Treating warnings as errors. Set documentation.nixos.options.warningsAreErrors " +
+        "to false to ignore these warnings." +
+        "\x1b[0m",
+        file=sys.stderr)
+    sys.exit(1)
 
 json.dump(unpivot(options), fp=sys.stdout)
diff --git a/nixos/modules/misc/documentation.nix b/nixos/modules/misc/documentation.nix
index f868e4b709a6..4451f3026f85 100644
--- a/nixos/modules/misc/documentation.nix
+++ b/nixos/modules/misc/documentation.nix
@@ -15,7 +15,7 @@ let
       f = import m;
       instance = f (mapAttrs (n: _: abort "evaluating ${n} for `meta` failed") (functionArgs f));
     in
-      cfg.nixos.splitOptionDocBuild
+      cfg.nixos.options.splitBuild
         && builtins.isPath m
         && isFunction f
         && instance ? options
@@ -101,6 +101,7 @@ let
               exit 1
             } >&2
         '';
+    inherit (cfg.nixos.options) warningsAreErrors;
   };
 
 
@@ -256,7 +257,7 @@ in
         '';
       };
 
-      nixos.splitOptionDocBuild = mkOption {
+      nixos.options.splitBuild = mkOption {
         type = types.bool;
         default = true;
         description = ''
@@ -266,6 +267,15 @@ in
         '';
       };
 
+      nixos.options.warningsAreErrors = mkOption {
+        type = types.bool;
+        default = true;
+        description = ''
+          Treat warning emitted during the option documentation build (eg for missing option
+          descriptions) as errors.
+        '';
+      };
+
       nixos.includeAllModules = mkOption {
         type = types.bool;
         default = false;