docs: render docs also for core modules

flake.nix

@@ -39,8 +39,25 @@
         value = modulesDir + "/${kind}/${fn}";
       })
       (readDir (modulesDir + "/${kind}"));
+
+    # expose core-modules at the top-level
+    corePath = ./modules/dream2nix/core;
+    coreDirs = filterAttrs (name: _: name != "default.nix") (readDir corePath);
+    coreModules =
+      mapAttrs'
+      (fn: _: {
+        name = removeSuffix ".nix" fn;
+        value = corePath + "/${fn}";
+      })
+      (filterAttrs (_: type: type == "regular" || type == "directory") coreDirs);
   in {
-    modules = mapAttrs (kind: _: mapModules kind) moduleKinds;
+    modules = let
+      allModules = mapAttrs (kind: _: mapModules kind) moduleKinds;
+    in
+      allModules
+      // {
+        dream2nix = allModules.dream2nix or {} // coreModules;
+      };
 
     lib = import ./lib {
       dream2nix = inputs.self;

modules/dream2nix/buildPythonPackage/interface.nix

@@ -36,6 +36,9 @@ in {
         default =
           config.deps.python.stdenv.hostPlatform
           == config.deps.python.stdenv.buildPlatform;
+        defaultText = ''
+          true if the host and build platforms are the same, false otherwise.
+        '';
       };
 
     dontWrapPythonPrograms =

modules/dream2nix/core/flags/default.nix

@@ -1,63 +1,5 @@
 {
-  config,
+  imports = [
-  lib,
+    ./interface.nix
-  ...
+  ];
-}: let
-  l = lib // builtins;
-  t = l.types;
-
-  mkFlag = description:
-    l.mkOption {
-      inherit description;
-      type = t.bool;
-      default = false;
-    };
-in {
-  options = {
-    /*
-    Helper option to define `flags`.
-    This makes the syntax for defining flags simpler and at the same time
-      prevents users to make mistakes like, for example, defining flags with
-      other types than bool.
-
-    This allows flags to be defined like this:
-    {
-      config.flagsOffered = {
-        enableFoo = "builds with foo support";
-        ...
-      };
-    }
-
-    ... instead of this:
-    {
-      options.flags = {
-        enableFoo = l.mkOption {
-          type = t.bool;
-          description = "builds with foo support";
-          default = false;
-        };
-        ...
-      }
-    }
-
-    */
-    flagsOffered = l.mkOption {
-      type = t.attrsOf t.str;
-      default = {};
-      description = ''
-        declare flags that can be used to enable/disable features
-      '';
-    };
-
-    # The flag options generated from `flagsOffered`
-    flags = l.mkOption {
-      type = t.submodule {
-        options = l.mapAttrs (_: mkFlag) config.flagsOffered;
-      };
-      default = {};
-      description = ''
-        Enable/disable flags declared in `flagsOffered`
-      '';
-    };
-  };
 }

modules/dream2nix/core/flags/interface.nix

@@ -0,0 +1,63 @@
+{
+  config,
+  lib,
+  ...
+}: let
+  l = lib // builtins;
+  t = l.types;
+
+  mkFlag = description:
+    l.mkOption {
+      inherit description;
+      type = t.bool;
+      default = false;
+    };
+in {
+  options = {
+    /*
+    Helper option to define `flags`.
+    This makes the syntax for defining flags simpler and at the same time
+      prevents users to make mistakes like, for example, defining flags with
+      other types than bool.
+
+    This allows flags to be defined like this:
+    {
+      config.flagsOffered = {
+        enableFoo = "builds with foo support";
+        ...
+      };
+    }
+
+    ... instead of this:
+    {
+      options.flags = {
+        enableFoo = l.mkOption {
+          type = t.bool;
+          description = "builds with foo support";
+          default = false;
+        };
+        ...
+      }
+    }
+
+    */
+    flagsOffered = l.mkOption {
+      type = t.attrsOf t.str;
+      default = {};
+      description = ''
+        declare flags that can be used to enable/disable features
+      '';
+    };
+
+    # The flag options generated from `flagsOffered`
+    flags = l.mkOption {
+      type = t.submodule {
+        options = l.mapAttrs (_: mkFlag) config.flagsOffered;
+      };
+      default = {};
+      description = ''
+        Enable/disable flags declared in `flagsOffered`
+      '';
+    };
+  };
+}

modules/dream2nix/core/lock/interface.nix

@@ -7,6 +7,7 @@
   t = l.types;
 in {
   imports = [
+    ../assertions.nix
     (lib.mkRemovedOptionModule ["lock" "repoRoot"] "Use paths.projectRoot instead.")
     (lib.mkRemovedOptionModule ["lock" "lockFileRel"] "Use paths.package instead.")
   ];

modules/dream2nix/nixpkgs-overrides/interface.nix

@@ -8,14 +8,14 @@
 in {
   options.nixpkgs-overrides = {
     enable =
-      (l.mkEnableOption "Whether to copy attributes, except those in `excluded` from nixpkgs")
+      (l.mkEnableOption "copying derivation attributes from a similar package in nixpkgs")
       // {
         default = true;
       };
 
     exclude = l.mkOption {
       type = t.listOf t.str;
-      description = "Attributes we do not want to copy from nixpkgs";
+      description = "Attribute names excluded from copying";
     };
 
     from = l.mkOption {

modules/dream2nix/nodejs-package-json/interface.nix

@@ -14,6 +14,7 @@ in {
       type = t.either t.path t.package;
       description = "Source of the package";
       default = config.mkDerivation.src;
+      defaultText = "config.mkDerivation.src";
     };
     npmArgs = {
       type = t.listOf t.str;

modules/dream2nix/pip/interface.nix

@@ -30,7 +30,7 @@ in {
       '';
       example = lib.literalExpression ''
         {
-          PIP_FIND_LINKS = "${config.deps.setuptools.dist}";
+          PIP_FIND_LINKS = "''${config.deps.setuptools.dist}";
         }
       '';
     };

modules/dream2nix/rust-cargo-lock/interface.nix

@@ -16,6 +16,7 @@ in {
       type = t.either t.path t.package;
       description = "Source of the package";
       default = config.mkDerivation.src;
+      defaultText = "config.mkDerivation.src";
     };
   };
 }

modules/flake-parts/render/default.nix

@@ -115,25 +115,32 @@ in {
       sourceName,
       sourcePath,
       baseUrl,
+      module,
       # coreOptDecls,
     }: let
       sourcePathStr = toString sourcePath;
+      moduleDir =
+        if ! lib.isPath module
+        then throw "module must be a string"
+        else if lib.hasSuffix ".nix" module
+        then builtins.dirOf module
+        else module;
+      # get the topLevel option names by inspecting the interface.nix
+      interfaceModuleFile = moduleDir + "/interface.nix";
+      interfaceModule = import interfaceModuleFile;
+      # call module with fake args just to get the top-level options
+      interface = interfaceModule (
+        (
+          lib.functionArgs interfaceModule
+        )
+        // {inherit lib;}
+      );
+      topLevelOptions =
+        if lib.pathExists interfaceModuleFile
+        then interface.options
+        else {};
     in
       opt: let
-        # get the topLevel option names by inspecting the interface.nix
-        interfaceModuleFile = ../../dream2nix + "/${sourceName}/interface.nix";
-        interfaceModule = import interfaceModuleFile;
-        # call module with fake args just to get the top-level options
-        interface = interfaceModule (
-          (
-            lib.functionArgs interfaceModule
-          )
-          // {inherit lib;}
-        );
-        topLevelOptions =
-          if lib.pathExists interfaceModuleFile
-          then interface.options
-          else {};
         declarations =
           concatMap
           (
@@ -313,7 +320,7 @@ in {
             else opts;
           documentType = "none";
           transformOptions = config.filterTransformOptions {
-            inherit (config) sourceName baseUrl sourcePath;
+            inherit (config) sourceName baseUrl sourcePath module;
             # inherit coreOptDecls;
           };
           warningsAreErrors = false; # not sure if feasible long term

modules/flake-parts/website.nix

@@ -13,12 +13,9 @@
     excludes = [
       # NOT WORKING
       # TODO: fix those
-      "nixpkgs-overrides"
       "core"
-      "flags"
       "ui"
       "docs"
-      "env"
       "assertions"
 
       # doesn't need to be rendered
@@ -33,7 +30,11 @@
         (self.modules.dream2nix))
       (name: module: {
         title = name;
-        module = self.modules.dream2nix.${name};
+        # module = self.modules.dream2nix.${name};
+        module =
+          if lib.pathExists (self.modules.dream2nix.${name} + /interface.nix)
+          then (self.modules.dream2nix.${name} + /interface.nix)
+          else module;
         sourcePath = self;
         attributePath = [
           "dream2nix"