groups: improve docs

modules/dream2nix/core/docs/book.toml

@@ -1,5 +1,5 @@
 [book]
-authors = ["Drv-Parts", "You"]
+authors = ["dream2nix", "You"]
 language = "en"
 multilingual = false
 src = "src"

modules/dream2nix/groups/README.md

@@ -0,0 +1,67 @@
+Module to deal with package sets (so called groups in dream2nix)
+
+
+## Separate different kinds of dependencies
+
+Many language specific package managers support declaration of different kinds of dependencies like, for example:
+  - `dependencies`, `devDependencies` in nodejs
+  - `dependencies`, `optional-dependencies.dev`, `optional-dependencies.test`, etc. in python
+
+The dream2nix groups module allows to keep the upstream separation by splitting the dependency definitions into different attribute sets located at:
+```
+config.groups.<group>.packages.<name>.<version>
+```
+
+This separation is relevant because not all dependencies are needed for all targets.
+A devShell for example requires the dev dependencies, while the runtime environment of the built package does not.
+
+## Re-use package definitions
+
+Each package definition in a group contains two important attributes:
+- `[...].packages.<name>.<version>.module`: for the package definition
+- `[...].packages.<name>.<version>.public`: for the final evaluated derivation
+
+Having the package definition (`module`) separated from the result allows to re-use the definition elsewhere.
+For example, a new group could be assembled by referring to the `modules` of existing groups:
+
+```nix
+{config, dream2nix, ...}: {
+
+  # The dev group
+  groups.dev = {
+
+    # a hello package
+    packages.hello."1.0.0".module = {
+      imports = [
+        dream2nix.modules.dream2nix.mkDerivation
+      ];
+      name = "hello";
+      version = "1.0.0";
+      mkDerivation.buildPhase = lib.mkForce ''echo "Hello World!" > $out''
+    };
+
+    # a modified hello package depending on the original hello definition
+    packages.hello-mod."1.0.0".module = {
+      blabla = {inherit wuhu;};
+      imports = [
+        # import the module definition of `hello` from above
+        config.groups.dev.packages.hello.module
+      ];
+      mkDerivation.buildPhase = ''echo "Good Bye World!" > $out'';
+    };
+  };
+
+  # The test group
+  groups.test = {
+
+    # a hello package based on `hello`` from the `dev` group
+    packages.hello."1.0.0".module = {
+      imports = [
+        # import the module definition of `hello` from the `dev` group
+        config.groups.dev.packages.hello.module
+      ];
+      mkDerivation.buildPhase = ''echo "Happy testing!" > $out''
+    };
+  }
+}
+```

modules/dream2nix/groups/group.nix

@@ -32,6 +32,29 @@ in {
       '';
     };
     packages = lib.mkOption {
+      description = ''
+        Contains all packages for the current group in the forma of a set like:
+        ```
+        {
+          package1."1.0.0" = {
+            module = {
+              # the package configuration
+            };
+            public = {
+              # the evaluated package
+            };
+          };
+          package2."1.0.0" = {
+            module = {
+              # the package configuration
+            };
+            public = {
+              # the evaluated package
+            };
+          };
+        }
+        ```
+      '';
       #      name           version       options
       type = t.lazyAttrsOf (t.lazyAttrsOf (t.submoduleWith {
         modules = [
@@ -68,9 +91,6 @@ in {
         ];
         inherit specialArgs;
       }));
-      description = ''
-        The packages for this group
-      '';
     };
   };
 }

modules/dream2nix/groups/interface.nix

@@ -17,7 +17,8 @@ in {
     groups = lib.mkOption {
       type = t.lazyAttrsOf groupType;
       description = ''
-        A set of packages
+        Holds multiple package sets (eg. groups).
+        Holds shared config (commonModule) and overrides on a global and on a per group basis.
       '';
     };
     commonModule = lib.mkOption {