From 0e97efbbef29dd7cdc07808f53557c8b71bd3e0c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Thalheim?= <joerg@thalheim.io>
Date: Mon, 7 Jul 2025 22:20:40 +0200
Subject: [PATCH] refactor: move docs transformOptions to clanLib to reduce
 rebuilds

- Add clanLib.docs.stripStorePathsFromDeclarations to deduplicate code
- Update all documentation generation to use the shared function
- This strips store paths from option declarations to prevent options.json
  from rebuilding when only store paths change but content remains the same
- Reduces unnecessary documentation rebuilds when making unrelated changes
---
 docs/nix/flake-module.nix              |  5 ++++-
 docs/nix/get-module-docs.nix           | 17 ++++++++++++++++-
 lib/default.nix                        |  1 +
 lib/docs.nix                           | 21 +++++++++++++++++++++
 lib/modules/eval-docs.nix              |  2 ++
 lib/modules/inventory/flake-module.nix |  1 +
 6 files changed, 45 insertions(+), 2 deletions(-)
 create mode 100644 lib/docs.nix

diff --git a/docs/nix/flake-module.nix b/docs/nix/flake-module.nix
index 642aa7bdc..9fd08108e 100644
--- a/docs/nix/flake-module.nix
+++ b/docs/nix/flake-module.nix
@@ -29,7 +29,10 @@
       # Frontmatter for clanModules
       clanModulesFrontmatter =
         let
-          docs = pkgs.nixosOptionsDoc { options = self.clanLib.modules.frontmatterOptions; };
+          docs = pkgs.nixosOptionsDoc {
+            options = self.clanLib.modules.frontmatterOptions;
+            transformOptions = self.clanLib.docs.stripStorePathsFromDeclarations;
+          };
         in
         docs.optionsJSON;
 
diff --git a/docs/nix/get-module-docs.nix b/docs/nix/get-module-docs.nix
index 9cb75e1a0..d6bc0e917 100644
--- a/docs/nix/get-module-docs.nix
+++ b/docs/nix/get-module-docs.nix
@@ -7,6 +7,10 @@
   pkgs,
   clan-core,
 }:
+let
+  inherit (clan-core.clanLib.docs) stripStorePathsFromDeclarations;
+  transformOptions = stripStorePathsFromDeclarations;
+in
 {
   # clanModules docs
   clanModulesViaNix = lib.mapAttrs (
@@ -20,6 +24,7 @@
           }).options
           ).clan.${name} or { };
         warningsAreErrors = true;
+        inherit transformOptions;
       }).optionsJSON
     else
       { }
@@ -32,6 +37,7 @@
       (nixosOptionsDoc {
         inherit options;
         warningsAreErrors = true;
+        inherit transformOptions;
       }).optionsJSON
     ) rolesOptions
   ) modulesRolesOptions;
@@ -52,7 +58,15 @@
 
         (nixosOptionsDoc {
           transformOptions =
-            opt: if lib.strings.hasPrefix "_" opt.name then opt // { visible = false; } else opt;
+            opt:
+            let
+              # Apply store path stripping first
+              transformed = transformOptions opt;
+            in
+            if lib.strings.hasPrefix "_" transformed.name then
+              transformed // { visible = false; }
+            else
+              transformed;
           options = (lib.evalModules { modules = [ role.interface ]; }).options;
           warningsAreErrors = true;
         }).optionsJSON
@@ -72,5 +86,6 @@
         }).options
         ).clan.core or { };
       warningsAreErrors = true;
+      inherit transformOptions;
     }).optionsJSON;
 }
diff --git a/lib/default.nix b/lib/default.nix
index 412f549ef..4606ecc83 100644
--- a/lib/default.nix
+++ b/lib/default.nix
@@ -45,6 +45,7 @@ lib.fix (
     introspection = import ./introspection { inherit lib; };
     jsonschema = import ./jsonschema { inherit lib; };
     facts = import ./facts.nix { inherit lib; };
+    docs = import ./docs.nix { inherit lib; };
 
     # flakes
     flakes = clanLib.callLib ./flakes.nix { };
diff --git a/lib/docs.nix b/lib/docs.nix
new file mode 100644
index 000000000..0e6cca95e
--- /dev/null
+++ b/lib/docs.nix
@@ -0,0 +1,21 @@
+{ lib, ... }:
+{
+  # Strip store paths from option declarations to make docs more stable
+  # This prevents documentation from rebuilding when store paths change
+  # but the actual content remains the same
+  stripStorePathsFromDeclarations = opt:
+    opt // {
+      declarations = map (decl:
+        if lib.isString decl && lib.hasPrefix "/nix/store/" decl then
+          let
+            parts = lib.splitString "/" decl;
+          in
+            if builtins.length parts > 4 then
+              "/" + lib.concatStringsSep "/" (lib.drop 4 parts)
+            else
+              decl
+        else
+          decl
+      ) opt.declarations;
+    };
+}
\ No newline at end of file
diff --git a/lib/modules/eval-docs.nix b/lib/modules/eval-docs.nix
index 23d0fcec6..a4016f6dc 100644
--- a/lib/modules/eval-docs.nix
+++ b/lib/modules/eval-docs.nix
@@ -9,9 +9,11 @@ let
       clan-core.modules.clan.default
     ];
   };
+
   evalDocs = pkgs.nixosOptionsDoc {
     options = eval.options;
     warningsAreErrors = false;
+    transformOptions = clan-core.clanLib.docs.stripStorePathsFromDeclarations;
   };
 in
 {
diff --git a/lib/modules/inventory/flake-module.nix b/lib/modules/inventory/flake-module.nix
index abfd01ffb..6a7717336 100644
--- a/lib/modules/inventory/flake-module.nix
+++ b/lib/modules/inventory/flake-module.nix
@@ -49,6 +49,7 @@ in
               prefix = [ ];
             }).options;
           warningsAreErrors = true;
+          transformOptions = self.clanLib.docs.stripStorePathsFromDeclarations;
         }).optionsJSON;
 
       # Run: nix-unit --extra-experimental-features flakes --flake .#legacyPackages.x86_64-linux.evalTests