From 6c097699f4bb477b383a826efcc68c8be1f253ca Mon Sep 17 00:00:00 2001
From: lassulus <git@lassul.us>
Date: Sun, 16 Nov 2025 01:14:49 +0700
Subject: [PATCH 1/2] WIP: add docs output

this will add some documentation to the generated modules when done,
currently this has a few flaws

Things TOOD:
- generate documentation for internal module
- filter out the baseModule options
- remove the stuff about nixos internals

Maybe a better approach would be a pure approach where ge generate the
strings directly, instead of relying on nixosOptionsDoc, which requires
pkgs.
---
 lib/default.nix     |  3 ++-
 lib/modules/doc.nix | 53 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)
 create mode 100644 lib/modules/doc.nix

diff --git a/lib/default.nix b/lib/default.nix
index 52ecc71..2a80dbf 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -218,7 +218,7 @@ let
       inherit modules class specialArgs;
     };
 
-  modules = lib.genAttrs [ "package" "wrapper" "meta" ] (name: import ./modules/${name}.nix);
+  modules = lib.genAttrs [ "doc" "package" "wrapper" "meta" ] (name: import ./modules/${name}.nix);
 
   /**
     Create a wrapper configuration using the NixOS module system.
@@ -332,6 +332,7 @@ let
               };
             }
           )
+          modules.doc
           modules.wrapper
           modules.meta
           wrapperModule
diff --git a/lib/modules/doc.nix b/lib/modules/doc.nix
new file mode 100644
index 0000000..696f947
--- /dev/null
+++ b/lib/modules/doc.nix
@@ -0,0 +1,53 @@
+{
+  options,
+  config,
+  lib,
+  wlib,
+  ...
+}:
+let
+  internalOptions = lib.flatten (
+    builtins.attrValues (
+      builtins.mapAttrs (
+        _: mod:
+        builtins.attrNames
+          (mod {
+            lib = null;
+            wlib = null;
+            config = null;
+            options = null;
+          }).options
+      ) wlib.modules
+    )
+  );
+  optionsToRender = builtins.removeAttrs options config.docs.ignoreOptions;
+  nixosOptionsDoc = config.pkgs.nixosOptionsDoc {
+    options = optionsToRender;
+    warningsAreErrors = config.docs.warningsAreErrors;
+  };
+in
+{
+  options.docs = {
+    ignoreOptions = lib.mkOption {
+      type = lib.types.listOf lib.types.str;
+      default = internalOptions;
+    };
+    warningsAreErrors = lib.mkOption {
+      type = lib.types.bool;
+      default = false; # TODO make this true
+      description = "Whether warnings during documentation generation should be treated as errors.";
+    };
+    asciiDoc = lib.mkOption {
+      type = lib.types.package;
+      default = nixosOptionsDoc.optionsAsciiDoc;
+    };
+    commonMark = lib.mkOption {
+      type = lib.types.package;
+      default = nixosOptionsDoc.optionsCommonMark;
+    };
+    json = lib.mkOption {
+      type = lib.types.package;
+      default = nixosOptionsDoc.optionsJSON;
+    };
+  };
+}

From 65c3f102376f6a53dd1a05ea9abe20a8d8384f19 Mon Sep 17 00:00:00 2001
From: zimward <zimward@zimward.moe>
Date: Tue, 13 Jan 2026 19:42:38 +0100
Subject: [PATCH 2/2] WIP: add HTML docs

---
 lib/modules/doc.nix | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/lib/modules/doc.nix b/lib/modules/doc.nix
index 696f947..7e6442d 100644
--- a/lib/modules/doc.nix
+++ b/lib/modules/doc.nix
@@ -20,7 +20,7 @@ let
       ) wlib.modules
     )
   );
-  optionsToRender = builtins.removeAttrs options config.docs.ignoreOptions;
+  optionsToRender = removeAttrs options config.docs.ignoreOptions;
   nixosOptionsDoc = config.pkgs.nixosOptionsDoc {
     options = optionsToRender;
     warningsAreErrors = config.docs.warningsAreErrors;
@@ -49,5 +49,17 @@ in
       type = lib.types.package;
       default = nixosOptionsDoc.optionsJSON;
     };
+    html = lib.mkOption {
+      type = lib.types.package;
+      default = config.pkgs.stdenvNoCC.mkDerivation {
+        name = "docs-${config.package.name}.html";
+        src = config.docs.commonMark;
+        dontUnpack = true;
+        nativeBuildInputs = [ config.pkgs.pandoc ];
+        buildPhase = ''
+          pandoc -f markdown -t html $src > $out
+        '';
+      };
+    };
   };
 }