From 100b968012804d6526c5f48a32c30680916bc474 Mon Sep 17 00:00:00 2001
From: Matt Sturgeon <matt@sturgeon.me.uk>
Date: Tue, 10 Jun 2025 19:33:29 +0100
Subject: [PATCH] doc: ensure `config` is not used in option docs

With a few exceptions for `lib.stylix` functions.

Once these exceptions are removed, we will have solved the issue with
NixOS's documentation.nixos.includeAllModules option.

See https://github.com/nix-community/stylix/issues/98
---
 doc/default.nix     | 35 +++++++++++++++++++++++++++++++++++
 doc/eval_compat.nix | 25 ++++++-------------------
 2 files changed, 41 insertions(+), 19 deletions(-)

diff --git a/doc/default.nix b/doc/default.nix
index 1b887713..25b8d503 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -25,12 +25,47 @@ let
     }) pkgs.formats;
   };
 
+  # A stub config used while evaluating the stylix modules for the docs
+  #
+  # TODO: remove all dependency on `config` and simplify to `noConfig = null`.
+  # Doing that should resolve https://github.com/nix-community/stylix/issues/98
+  noConfig =
+    let
+      configuration = evalDocs {
+        # The config.lib option, as found in NixOS and home-manager.
+        # Required by the `target.nix` module.
+        options.lib = lib.mkOption {
+          type = lib.types.attrsOf lib.types.attrs;
+          description = ''
+            This option allows modules to define helper functions, constants, etc.
+          '';
+          default = { };
+          visible = false;
+        };
+
+        # The target.nix module defines functions that are currently needed to
+        # declare options
+        imports = [ ../stylix/target.nix ];
+      };
+    in
+    {
+      lib.stylix = {
+        inherit (configuration.config.lib.stylix)
+          mkEnableIf
+          mkEnableTarget
+          mkEnableTargetWith
+          mkEnableWallpaper
+          ;
+      };
+    };
+
   evalDocs =
     module:
     lib.evalModules {
       modules = [ ./eval_compat.nix ] ++ lib.toList module;
       specialArgs = {
         pkgs = noPkgs;
+        config = noConfig;
       };
     };
 
diff --git a/doc/eval_compat.nix b/doc/eval_compat.nix
index 08822105..daf4b87f 100644
--- a/doc/eval_compat.nix
+++ b/doc/eval_compat.nix
@@ -1,24 +1,11 @@
 { lib, ... }:
 {
-  options = {
-    # Declare the arbitrarily named __stub attribute to allow modules to evaluate
-    # 'options.programs ? «OPTION»'.
-    #
-    # TODO: Replace 'options.programs ? «OPTION»' instances with
-    # 'options ? programs.«OPTION»' to remove this __stub workaround.
-    programs.__stub = lib.mkSinkUndeclaredOptions { };
-
-    # The config.lib option, as found in NixOS and home-manager.
-    # Many option declarations depend on `config.lib.stylix`.
-    lib = lib.mkOption {
-      type = lib.types.attrsOf lib.types.attrs;
-      description = ''
-        This option allows modules to define helper functions, constants, etc.
-      '';
-      default = { };
-      visible = false;
-    };
-  };
+  # Declare the arbitrarily named __stub attribute to allow modules to evaluate
+  # 'options.programs ? «OPTION»'.
+  #
+  # TODO: Replace 'options.programs ? «OPTION»' instances with
+  # 'options ? programs.«OPTION»' to remove this __stub workaround.
+  options.programs.__stub = lib.mkSinkUndeclaredOptions { };
 
   # Third-party options are not included in the module eval,
   # so disable checking options definitions have matching declarations