zfs-with-vdevs: add an example for using absolute device paths

This is the only way to assign devices rather than fixed gpt partitions.
Without reading the code it's not very obvious how disko actually
assigns devices to zpools.

Author: Mic92

example/zfs-with-vdevs.nix

@@ -244,11 +244,14 @@
             type = "topology";
             vdev = [
               {
-                mode = "mirror";
-                members = [ "data1" "data2" ];
+                # This syntax expects a disk called 'data3' with a gpt partition called 'zfs'.
+                members = [ "data1" ];
+                # It's also possible to use the full path of the device or partition
+                # members = [ "/dev/disk/by-id/wwn-0x5000c500af8b2a14" ];
               }
               {
-                members = [ "data3" ];
+                mode = "mirror";
+                members = [ "data2" "data3" ];
               }
             ];
             spare = [ "spare" ];

lib/types/zpool.nix

@@ -25,6 +25,44 @@ in
     };
     mode = lib.mkOption {
       default = "";
+      example = {
+        mode = {
+          topology = {
+            type = "topology";
+            vdev = [
+              {
+                # Members can be either specified by a full path or by a disk name
+                # This is example uses the full path
+                members = [ "/dev/disk/by-id/wwn-0x5000c500af8b2a14" ];
+              }
+            ];
+            log = [
+              {
+                # Example using gpt partition labels
+                # This expects an disk called `ssd` with a gpt partition called `zfs`
+                #   disko.devices.disk.ssd = {
+                #    type = "disk";
+                #    device = "/dev/nvme0n1";
+                #    content = {
+                #      type = "gpt";
+                #      partitions = {
+                #        zfs = {
+                #          size = "100%";
+                #          content = {
+                #            type = "zfs";
+                #            # use your own pool name here
+                #            pool = "zroot";
+                #          };
+                #        };
+                #      };
+                #    };
+                #  };
+                members = [ "ssd" ];
+              }
+            ];
+          };
+        };
+      };
       type = (lib.types.oneOf [
         (lib.types.enum modeOptions)
         (lib.types.attrsOf (diskoLib.subType {

tests/zfs-with-vdevs.nix

@@ -57,9 +57,9 @@ diskoLib.testLib.makeDiskoTest {
             vdev = ""
     actual.sort()
     expected=sorted([
-      'zroot /dev/disk/by-partlabel/disk-data3-zfs',
-      'zroot mirror /dev/disk/by-partlabel/disk-data1-zfs',
+      'zroot /dev/disk/by-partlabel/disk-data1-zfs',
       'zroot mirror /dev/disk/by-partlabel/disk-data2-zfs',
+      'zroot mirror /dev/disk/by-partlabel/disk-data3-zfs',
       'dedup /dev/disk/by-partlabel/disk-dedup3-zfs',
       'dedup mirror /dev/disk/by-partlabel/disk-dedup1-zfs',
       'dedup mirror /dev/disk/by-partlabel/disk-dedup2-zfs',