From d7378d8ba82d0ef82d9b638dae2cc6b5b3eb19ab Mon Sep 17 00:00:00 2001
From: Birdee <85372418+BirdeeHub@users.noreply.github.com>
Date: Tue, 25 Aug 2026 21:16:42 -0700
Subject: [PATCH] fix(docgen): docgen no longer omits options not in the main
 file

previously, the docgen would ignore any option declared in a file which
was not one with the maintainers and description fields populated.

Now it should properly include the options for those other files, under
the nearest importing module with maintainers or description fields
populated

This was the next step required before moving forward with exposing
functionality for generating docs for standalone 3rd party modules
---
 ci/docs/per-mod/normopts.nix | 92 +++++++++++++++++++++++-------------
 ci/docs/per-mod/rendermd.nix |  8 +++-
 2 files changed, 67 insertions(+), 33 deletions(-)

diff --git a/ci/docs/per-mod/normopts.nix b/ci/docs/per-mod/normopts.nix
index 5d902a7b..79c79d0a 100644
--- a/ci/docs/per-mod/normopts.nix
+++ b/ci/docs/per-mod/normopts.nix
@@ -169,22 +169,67 @@ let
   hidden = groupByDecl invisible.wrong;
   visible = groupByDecl partitioned.wrong;
 
+  collectAssociatedOptions =
+    visiblity: groupedOptions:
+    {
+      unassociated ? { },
+      modules-by-meta,
+    }:
+    let
+      isAssociated = file: module: builtins.any (n: lib.hasInfix n file) (module.associated or [ ]);
+      associations = builtins.mapAttrs (
+        file: _: lib.lists.findFirstIndex (isAssociated file) null modules-by-meta
+      ) groupedOptions;
+    in
+    {
+      modules-by-meta = lib.imap0 (
+        i: module:
+        let
+          opts =
+            module.${visiblity} or [ ]
+            ++ builtins.concatLists (
+              lib.mapAttrsToList (file: index: if index == i then groupedOptions.${file} else [ ]) associations
+            );
+        in
+        module
+        // {
+          ${if opts != [ ] then visiblity else null} = opts;
+        }
+      ) modules-by-meta;
+      unassociated = unassociated // {
+        ${visiblity} =
+          unassociated.${visiblity} or [ ]
+          ++ builtins.concatLists (
+            lib.mapAttrsToList (file: index: if index == null then groupedOptions.${file} else [ ]) associations
+          );
+      };
+    };
+
 in
-lib.pipe modules-by-meta [
-  (builtins.concatMap (
-    v:
-    lib.optional (internal ? "${v.file}" || hidden ? "${v.file}" || visible ? "${v.file}") (
-      v
-      // {
-        ${if internal ? "${v.file}" then "internal" else null} =
-          internal.${v.file} ++ lib.optional (v.file == anon_name) (internal.${anon_name} or [ ]);
-        ${if hidden ? "${v.file}" then "hidden" else null} =
-          hidden.${v.file} ++ lib.optional (v.file == anon_name) (hidden.${anon_name} or [ ]);
-        ${if visible ? "${v.file}" then "visible" else null} =
-          visible.${v.file} ++ lib.optional (v.file == anon_name) (visible.${anon_name} or [ ]);
-      }
-    )
-  ))
+lib.pipe { inherit modules-by-meta; } [
+  (collectAssociatedOptions "visible" visible)
+  (collectAssociatedOptions "hidden" hidden)
+  (collectAssociatedOptions "internal" internal)
+  (
+    { unassociated, modules-by-meta }:
+    let
+      modules-filtered = builtins.filter (
+        v: v.visible or [ ] != [ ] || v.hidden or [ ] != [ ] || v.internal or [ ] != [ ]
+      ) modules-by-meta;
+      anon_module = {
+        file = anon_name;
+        ${if unassociated.visible or [ ] != [ ] then "visible" else null} = unassociated.visible or [ ];
+        ${if unassociated.hidden or [ ] != [ ] then "hidden" else null} = unassociated.hidden or [ ];
+        ${if unassociated.internal or [ ] != [ ] then "internal" else null} = unassociated.internal or [ ];
+      };
+    in
+    lib.reverseList modules-filtered
+    ++ lib.optional (
+      anon_module.visible or [ ] != [ ]
+      || anon_module.hidden or [ ] != [ ]
+      || anon_module.internal or [ ] != [ ]
+    ) anon_module
+  )
   (
     normed:
     if builtins.isBool includeCore && includeCore == true then
@@ -192,21 +237,4 @@ lib.pipe modules-by-meta [
     else
       builtins.filter (v: v.file != wlib.core) normed
   )
-  (
-    v:
-    lib.reverseList v
-    ++
-      lib.optional
-        (
-          builtins.all (v: v.file != anon_name) v && internal ? "${anon_name}"
-          || hidden ? "${anon_name}"
-          || visible ? "${anon_name}"
-        )
-        {
-          file = anon_name;
-          ${if internal ? "${anon_name}" then "internal" else null} = internal.${anon_name};
-          ${if hidden ? "${anon_name}" then "hidden" else null} = hidden.${anon_name};
-          ${if visible ? "${anon_name}" then "visible" else null} = visible.${anon_name};
-        }
-  )
 ]
diff --git a/ci/docs/per-mod/rendermd.nix b/ci/docs/per-mod/rendermd.nix
index c40d2289..51c90dcb 100644
--- a/ci/docs/per-mod/rendermd.nix
+++ b/ci/docs/per-mod/rendermd.nix
@@ -34,11 +34,17 @@
   declaredBy ?
     { declarations, ... }:
     let
+      removeViaOption =
+        str:
+        let
+          match = builtins.match "^(.*), via option .*$" str;
+        in
+        if match != null then builtins.elemAt match 0 else str;
       linkDest =
         v:
         if lib.hasPrefix wlib.modulesPath v then
           "https://github.com/BirdeeHub/nix-wrapper-modules/blob/main"
-          + lib.removePrefix wlib.modulesPath (toString v)
+          + lib.removePrefix wlib.modulesPath (removeViaOption (toString v))
         else
           toString v;
       linkName = v: lib.removeSuffix "/module.nix" (lib.removePrefix "${wlib.modulesPath}/" (toString v));