ci(docgen): docs now warn/throw on missing descriptions again (#289)

and because we now build those in the tests, it tells us BEFORE the PR
is merged

Author: BirdeeHub

ci/docs/default.nix

@@ -16,6 +16,7 @@ let
       descriptionStartsOpen ? null,
       descriptionIncluded ? null,
       moduleStartsOpen ? null,
+      warningsAreErrors ? true,
     }:
     name: module:
     (if title != null then "# ${title}\n\n" else "# `${prefix}${name}`\n\n")
@@ -29,7 +30,7 @@ let
         }
       ]
       // {
-        inherit includeCore;
+        inherit includeCore warningsAreErrors;
         ${if descriptionStartsOpen != null then "descriptionStartsOpen" else null} = descriptionStartsOpen;
         ${if descriptionIncluded != null then "descriptionIncluded" else null} = descriptionIncluded;
         ${if moduleStartsOpen != null then "moduleStartsOpen" else null} = moduleStartsOpen;
@@ -42,13 +43,18 @@ in
     wlib.wrapperModules.mdbook
     ./redirects.nix
   ];
-  mainBook = "nix-wrapper-modules";
-  outputs = [
+  config.mainBook = "nix-wrapper-modules";
+  config.outputs = [
     "out"
     "generated"
   ];
-  drv.unsafeDiscardReferences.generated = true;
-  drv.preBuild = ''
+  options.warningsAreErrors = lib.mkOption {
+    type = lib.types.bool;
+    default = true;
+    description = "Whether warnings in the docgen should be treated as errors (i.e. missing descriptions)";
+  };
+  config.drv.unsafeDiscardReferences.generated = true;
+  config.drv.preBuild = ''
     mkdir -p "$generated/wrapper_docs"
     jq -r '.wrapper_docs | to_entries[] | @base64' "$NIX_ATTRS_JSON_FILE" | while read -r entry; do
       # decode base64 to get JSON safely
@@ -61,10 +67,11 @@ in
       echo "$(echo "$decoded" | jq -r '.value')" > "$generated/module_docs/$(echo "$decoded" | jq -r '.key').md"
     done
   '';
-  drv.module_docs = builtins.mapAttrs (buildModuleDocs {
+  config.drv.module_docs = builtins.mapAttrs (buildModuleDocs {
     prefix = "wlib.modules.";
     package = pkgs.hello;
     includeCore = false;
+    inherit (config) warningsAreErrors;
     moduleStartsOpen = _: _: true;
     descriptionStartsOpen =
       _: _: _:
@@ -73,14 +80,16 @@ in
       _: _: _:
       true;
   }) wlib.modules;
-  drv.wrapper_docs = builtins.mapAttrs (buildModuleDocs {
+  config.drv.wrapper_docs = builtins.mapAttrs (buildModuleDocs {
     prefix = "wlib.wrapperModules.";
+    inherit (config) warningsAreErrors;
   }) wlib.wrapperModules;
-  drv.core_docs = buildModuleDocs {
+  config.drv.core_docs = buildModuleDocs {
     package = pkgs.hello;
+    inherit (config) warningsAreErrors;
     title = "Core (builtin) Options set";
   } "core" { };
-  books.nix-wrapper-modules = {
+  config.books.nix-wrapper-modules = {
     book = {
       book = {
         src = "src";

ci/docs/per-mod/default.nix

@@ -69,8 +69,6 @@ rec {
         builtins.unsafeDiscardStringContext
       ];
 
-  # TODO: should have a warning for missing descriptions
-  # and also a warnings as errors setting
   wrapperModuleMD = import ./rendermd.nix {
     inherit
       wlib

ci/docs/per-mod/rendermd.nix

@@ -11,6 +11,7 @@
   includeCore ? true,
   transform ? null,
   prefix ? false,
+  warningsAreErrors ? true,
   nameFromModule ?
     { file, ... }:
     lib.removeSuffix "/module.nix" (lib.removePrefix "${wlib.modulesPath}/" (toString file)),
@@ -65,20 +66,33 @@ let
     lib.optionalString (opt ? "${n}" && lib.isStringLike opt.${n}) (
       lib.optionalString (desc != "") "${desc}\n" + "${opt.${n}}\n\n"
     );
-  renderOption = opt: ''
-    ## `${lib.options.showOption (opt.loc or [ ])}`
+  mkWarn = opt: "nix-wrapper-modules docgen warning: Option ${opt.name} has no description";
+  renderOption =
+    opt:
+    # TODO: This should probably collect all the warnings until the end
+    # so it says everything which is missing a description
+    # rather than just the first one even if warningsAreErrors is true.
+    # For now, one can run it with warningsAreErrors = false to see them all.
+    (
+      if opt.description or "" == "" || opt.description or null == null then
+        if warningsAreErrors == true then throw (mkWarn opt) else lib.warn (mkWarn opt)
+      else
+        (v: v)
+    )
+      ''
+        ## `${lib.options.showOption (opt.loc or [ ])}`
 
-    ${mkOptField opt "description" ""}${mkOptField opt "relatedPackages" "Related packages:\n"}${
-      mkOptField opt "type" "Type:${lib.optionalString (opt.readOnly or false == true) " (read-only)"}"
-    }${mkOptField opt "default" "Default:"}${mkOptField opt "example" "Example:"}${
-      lib.optionalString (opt.declarations or [ ] != [ ]) ''
-        Declared by:
+        ${mkOptField opt "description" ""}${mkOptField opt "relatedPackages" "Related packages:\n"}${
+          mkOptField opt "type" "Type:${lib.optionalString (opt.readOnly or false == true) " (read-only)"}"
+        }${mkOptField opt "default" "Default:"}${mkOptField opt "example" "Example:"}${
+          lib.optionalString (opt.declarations or [ ] != [ ]) ''
+            Declared by:
 
-        ${declaredBy opt}
+            ${declaredBy opt}
 
-      ''
-    }
-  '';
+          ''
+        }
+      '';
   renderModule =
     i: mod:
     let

ci/flake.nix

@@ -58,10 +58,11 @@
         system: (wlib-flake (import nixpkgs { inherit system; })).formatter.${system}
       );
       packages = forAllSystems (system: {
-        default = self.packages.${system}.docs;
+        default = self.packages.${system}.docs.wrap { warningsAreErrors = true; };
         docs = wlib.evalPackage [
           ./docs
           {
+            warningsAreErrors = false;
             pkgs = import nixpkgs {
               inherit system;
               config = {

wrapperModules/m/mdbook/module.nix

@@ -209,6 +209,22 @@ in
       '';
     };
     books = lib.mkOption {
+      description = ''
+        A set of books to generate along with the mdbook derivation.
+
+        It will also create a build script for each one.
+
+        That build script will be a wrapped mdbook executable.
+
+        It will run something like the following:
+
+        `mdbook build -d $firstArg "''${otherArgs[@]}" <generated-book-subdir>`
+
+        You could modify it further with the `wrapperVariants` attribute of the same name,
+        for example to add a `-o` flag.
+
+        Or use it as the main command for running via `nix run` in a build pipeline using `mainBook = "this_book";`
+      '';
       default = { };
       type = lib.types.attrsOf (
         lib.types.submodule (