[release-25.05] doc: use stricter, more minimal module evals

doc/default.nix

@@ -1,10 +1,7 @@
 {
   lib,
   pkgs,
-  inputs,
-  nixosSystem,
-  homeManagerConfiguration,
-  system,
+  self,
   callPackage,
   writeText,
   stdenvNoCC,
@@ -17,38 +14,74 @@ let
   # Prefix to remove from option declaration file paths.
   rootPrefix = toString ../. + "/";
 
-  nixosConfiguration = nixosSystem {
-    inherit system;
-    modules = [
-      inputs.home-manager.nixosModules.home-manager
-      inputs.self.nixosModules.stylix
-    ];
+  # A stub pkgs used while evaluating the stylix modules for the docs
+  noPkgs = {
+    # Needed for type-checking
+    inherit (pkgs) _type;
+
+    # Permit access to (pkgs.formats.foo { }).type
+    formats = builtins.mapAttrs (_: fmt: args: {
+      inherit (fmt args) type;
+    }) pkgs.formats;
   };
 
-  homeConfiguration = homeManagerConfiguration {
-    inherit pkgs;
-    modules = [
-      inputs.self.homeModules.stylix
-      {
-        home = {
-          homeDirectory = "/home/book";
-          stateVersion = "22.11";
-          username = "book";
+  # 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;
+      };
+    };
 
   # TODO: Include Nix Darwin options
 
   platforms = {
     home_manager = {
       name = "Home Manager";
-      configuration = homeConfiguration;
+      configuration = evalDocs [
+        self.homeModules.stylix
+        ./hm_compat.nix
+      ];
     };
     nixos = {
       name = "NixOS";
-      configuration = nixosConfiguration;
+      configuration = evalDocs self.nixosModules.stylix;
     };
   };
 
@@ -339,7 +372,7 @@ let
 
   # Permalink to view a source file on GitHub. If the commit isn't known,
   # then fall back to the latest commit.
-  declarationCommit = inputs.self.rev or "master";
+  declarationCommit = self.rev or "master";
   declarationPermalink = "https://github.com/nix-community/stylix/blob/${declarationCommit}";
 
   # Renders a single option declaration. Example output:

doc/eval_compat.nix

@@ -0,0 +1,13 @@
+{ lib, ... }:
+{
+  # 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
+  config._module.check = false;
+}

doc/hm_compat.nix

@@ -0,0 +1,12 @@
+{ lib, ... }:
+{
+  # Declare the arbitrarily named __stub attribute to allow modules to evaluate
+  # 'options.services ? «OPTION»'.
+  #
+  # TODO: Replace 'options.services ? «OPTION»' instances with
+  # 'options ? services.«OPTION»' to remove this __stub workaround.
+  options.services.__stub = lib.mkSinkUndeclaredOptions { };
+
+  # Some modules use home-manager's `osConfig` arg
+  config._module.args.osConfig = null;
+}

flake/packages.nix

@@ -21,9 +21,7 @@
         ))
         {
           doc = pkgs.callPackage ../doc {
-            inherit inputs;
-            inherit (inputs.nixpkgs.lib) nixosSystem;
-            inherit (inputs.home-manager.lib) homeManagerConfiguration;
+            inherit (inputs) self;
           };
           serve-docs = pkgs.callPackage ../doc/server.nix {
             inherit (config.packages) doc;

stylix/fonts.nix

@@ -58,7 +58,12 @@ in
         mkFontSizeOption =
           { default, target }:
           lib.mkOption {
-            inherit default;
+            default = if builtins.isInt default then default else cfg.sizes.${default};
+            defaultText =
+              if builtins.isInt default then
+                default
+              else
+                lib.literalExpression "config.stylix.fonts.sizes.${default}";
 
             description = ''
               The font size used for ${target}.
@@ -94,12 +99,12 @@ in
 
         terminal = mkFontSizeOption {
           target = "terminals and text editors";
-          default = cfg.sizes.applications;
+          default = "applications";
         };
 
         popups = mkFontSizeOption {
           target = "notifications, popups, and other overlay elements of the desktop";
-          default = cfg.sizes.desktop;
+          default = "desktop";
         };
       };
 

stylix/target.nix

@@ -113,7 +113,11 @@
               lib.literalExpression "config.stylix.image != null"
             else
               false;
-          example = config.stylix.image == null;
+          example =
+            if autoEnable then
+              lib.literalExpression "config.stylix.image == null"
+            else
+              true;
         };
 
       mkEnableIf =