From 29d617ecc8bba39853fcf3543c51de95455b3159 Mon Sep 17 00:00:00 2001
From: Austin Horstman <khaneliman12@gmail.com>
Date: Thu, 12 Feb 2026 22:07:55 -0600
Subject: [PATCH] docs: improve submodule options rendering

Certain types don't offer `getSubOptions` upstream in nixpkgs, at the
moment. We can do some overriding and manually calling it for now to
fetch the options for docs.

Signed-off-by: Austin Horstman <khaneliman12@gmail.com>
---
 docs/default.nix | 56 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 54 insertions(+), 2 deletions(-)

diff --git a/docs/default.nix b/docs/default.nix
index 0d8bc8c2..f374f93b 100644
--- a/docs/default.nix
+++ b/docs/default.nix
@@ -69,6 +69,57 @@ let
 
   hmPath = toString ./..;
 
+  # Keep submodule option docs visible when wrapped in `either` (and therefore
+  # in `nullOr (either ...)`), which upstream currently omits.
+  docsLib = lib.extend (
+    _self: super:
+    let
+      mergeEitherSubOptions =
+        prefix: leftType: rightType:
+        let
+          getSubOptionsOrEmpty =
+            optionType:
+            let
+              subOptions = optionType.getSubOptions prefix;
+            in
+            if builtins.isAttrs subOptions then subOptions else { };
+
+          mkOptionDecl = options: {
+            _file = "<docs/default.nix>";
+            pos = null;
+            inherit options;
+          };
+
+          optionSets = lib.filter (options: options != { }) [
+            (getSubOptionsOrEmpty leftType)
+            (getSubOptionsOrEmpty rightType)
+          ];
+          mergedOptions = lib.foldl' (
+            acc: options:
+            if acc == { } then
+              options
+            else
+              (super.mergeOptionDecls prefix [
+                (mkOptionDecl acc)
+                (mkOptionDecl options)
+              ]).options
+          ) { } optionSets;
+        in
+        mergedOptions;
+
+    in
+    {
+      types = super.types // {
+        either =
+          leftType: rightType:
+          (super.types.either leftType rightType)
+          // {
+            getSubOptions = prefix: mergeEitherSubOptions prefix leftType rightType;
+          };
+      };
+    }
+  );
+
   buildOptionsDocs =
     args@{
       modules,
@@ -103,7 +154,7 @@ let
         };
 
       options =
-        (lib.evalModules {
+        (docsLib.evalModules {
           modules = modules ++ [ poisonModule ];
           class = "homeManager";
         }).options;
@@ -141,7 +192,8 @@ let
   hmOptionsDocs = buildOptionsDocs {
     modules =
       import ../modules/modules.nix {
-        inherit lib pkgs;
+        lib = docsLib;
+        inherit pkgs;
         check = false;
       }
       ++ [ scrubbedPkgsModule ];