docs: cleanup, fix links, add comments

docs/content/examples/deployment/default.nix

@@ -1,9 +1,12 @@
-{kubenix ? import ../../../..}:
-kubenix.evalModules.x86_64-linux {
-  module = {kubenix, ...}: {
-    imports = [./module.nix];
+{ kubenix ? import ../../../.. }:
+kubenix.evalModules.${builtins.currentSystem} {
+  module = { kubenix, ... }: {
+    # instead of defining everything inline, let's import it
+    imports = [ ./module.nix ];
 
+    # annotate the generated resources with a project name
     kubenix.project = "example";
+    # define a target api version to validate output
     kubernetes.version = "1.24";
   };
 }

docs/content/examples/deployment/module.nix

@@ -1,11 +1,5 @@
-{
-  config,
-  lib,
-  pkgs,
-  kubenix,
-  ...
-}: {
-  imports = with kubenix.modules; [k8s];
+{ kubenix, ... }: {
+  imports = [ kubenix.modules.k8s ];
 
   kubernetes.resources = {
     deployments.nginx.spec = {
@@ -56,13 +50,11 @@
     };
 
     services.nginx.spec = {
-      ports = [
-        {
-          name = "http";
-          port = 80;
-        }
-      ];
       selector.app = "nginx";
+      ports = [{
+        name = "http";
+        port = 80;
+      }];
     };
   };
 }

docs/content/examples/helm/default.nix

@@ -1,16 +1,16 @@
-{kubenix ? import ../../../..}:
+{ kubenix ? import ../../../.. }:
 kubenix.evalModules.${builtins.currentSystem} {
-  module = {kubenix, ...}: {
-    imports = with kubenix.modules; [helm];
+  module = { kubenix, ... }: {
+    imports = [ kubenix.modules.helm ];
     kubernetes.helm.releases.example = {
       chart = kubenix.lib.helm.fetch {
-        chart = "nginx";
         repo = "https://charts.bitnami.com/bitnami";
-        sha256 = "sha256-wP3tcBnySx+kvZqfW2W9k665oi8KOI50tCcAl0g9cuw=";
-      };
-      values = {
-        replicaCount = 2;
+        chart = "nginx";
+        version = "15.0.1";
+        sha256 = "sKVqx99O4SNIq5y8Qo/b/2xIqXqSsZJzrgnYYz/0TKg=";
       };
+      # arbitrary attrset passed as values to the helm release
+      values.replicaCount = 2;
     };
   };
 }

docs/content/examples/image/_index.md

@@ -4,8 +4,8 @@ weight: 30
 
 Instead of deploying a 3rd party image, we can build our own.
 
-We rely on the upstream [`dockerTools`](https://github.com/NixOs/nixpkgs/tree/master/pkgs/built-support/docker) package here.
-Specifically, we can use the `buildImage` function to define our image:
+We rely on the upstream [`dockerTools`](https://nixos.org/manual/nixpkgs/stable/#sec-pkgs-dockerTools) package here.
+Specifically, we can use the `buildLayeredImage` function to define our image:
 
 {{< source "image.nix" >}}
 
@@ -60,7 +60,5 @@ Render the generated manifests again and see that it now refers to the newly bui
 Of course, to actually deploy, we need to push the image to our registry. The script defined at {{< option "docker.copyScript" >}} does just that.
 
 ```sh
-$(nix build -f . --json config.docker.copyScript | jq -r '.[].outputs.out')
+$(nix build -f . --print-out-paths config.docker.copyScript)
 ```
-
- <!-- TODO: can we make that `nix run -f . config.docker.copyScript` ? -->

docs/content/examples/image/default.nix

@@ -1,15 +1,10 @@
-{kubenix ? import ../../../..}:
+{ kubenix ? import ../../../.. }:
 kubenix.evalModules.${builtins.currentSystem} {
-  module = {
-    kubenix,
-    config,
-    pkgs,
-    ...
-  }: {
-    imports = with kubenix.modules; [k8s docker];
+  module = { kubenix, config, pkgs, ... }: {
+    imports = with kubenix.modules; [ k8s docker ];
     docker = {
       registry.url = "docker.somewhere.io";
-      images.example.image = pkgs.callPackage ./image.nix {};
+      images.example.image = pkgs.callPackage ./image.nix { };
     };
     kubernetes.resources.pods.example.spec.containers = {
       custom.image = config.docker.images.example.path;

docs/content/examples/image/image.nix

@@ -1,10 +1,7 @@
-{
-  dockerTools,
-  nginx,
-}:
+{ dockerTools, nginx }:
 dockerTools.buildLayeredImage {
   name = "nginx";
-  contents = [nginx];
+  contents = [ nginx ];
   extraCommands = ''
     mkdir -p etc
     chmod u+w etc
@@ -12,9 +9,9 @@ dockerTools.buildLayeredImage {
     echo "nginx:x:1000:nginx" > etc/group
   '';
   config = {
-    Cmd = ["nginx" "-c" "/etc/nginx/nginx.conf"];
+    Cmd = [ "nginx" "-c" "/etc/nginx/nginx.conf" ];
     ExposedPorts = {
-      "80/tcp" = {};
+      "80/tcp" = { };
     };
   };
 }

docs/content/examples/namespaces/default.nix

@@ -1,7 +1,7 @@
-{kubenix ? import ../../../..}:
-kubenix.evalModules.x86_64-linux {
-  module = {kubenix, ...}: {
-    imports = [./module.nix];
+{ kubenix ? import ../../../.. }:
+kubenix.evalModules.${builtins.currentSystem} {
+  module = { kubenix, ... }: {
+    imports = [ ./module.nix ];
 
     kubenix.project = "multi-namespace-example";
     kubernetes.version = "1.24";

docs/content/examples/pod/default.nix

@@ -1,12 +1,18 @@
 # let's creata a function whose only input is the kubenix package
-{kubenix ? import ../../../..}:
+{ kubenix ? import ../../../.. }:
 # evalModules is our main entrypoint
 kubenix.evalModules.${builtins.currentSystem} {
   # to it, we pass a module that accepts a (different) kubenix object
-  module = {kubenix, ...}: {
+  module = { kubenix, ... }: {
     # in order to define options, we need to import their definitions
-    imports = with kubenix.modules; [k8s];
+    imports = [ kubenix.modules.k8s ];
     # now we have full access to define Kubernetes resources
-    kubernetes.resources.pods.example.spec.containers.ex.image = "nginx";
+    kubernetes.resources.pods = {
+      # "example" is the name of our pod
+      example.spec.containers = {
+        # "ex" is the name of the container in our pod
+        ex.image = "nginx";
+      };
+    };
   };
 }

docs/content/examples/secrets/default.nix

@@ -1,7 +1,7 @@
-{kubenix ? import ../../../..}:
-kubenix.evalModules.x86_64-linux {
-  module = {kubenix, ...}: {
-    imports = with kubenix; [k8s];
+{ kubenix ? import ../../../.. }:
+kubenix.evalModules.${builtins.currentSystem} {
+  module = { kubenix, ... }: {
+    imports = [ kubenix.modules.k8s ];
     kubernetes.resources.secrets.example.stringData = {
       password = "ref+file:///path/to/secret";
     };

docs/content/examples/testing/_index.md

@@ -1,8 +1,8 @@
-Testing is still very much in flux but here's a rough example.
+Testing is still very much in flux (contributions welcome!) but here's a rough example.
 
 {{< source "default.nix" >}}
 
-Where we've defined a might look like:
+Where we've defined a test that might look like:
 
 {{< source "test.nix" >}}
 

docs/content/examples/testing/default.nix

@@ -1,17 +1,15 @@
-{kubenix ? import ../../../..}:
-kubenix.evalModules.x86_64-linux {
-  module = {kubenix, ...}: {
-    imports = with kubenix.modules; [testing];
+{ kubenix ? import ../../../.. }:
+kubenix.evalModules.${builtins.currentSystem} {
+  module = { kubenix, ... }: {
+    imports = [ kubenix.modules.testing ];
     testing = {
-      tests = [./test.nix];
-      common = [
-        {
-          features = ["k8s"];
-          options = {
-            kubernetes.version = "1.24";
-          };
-        }
-      ];
+      tests = [ ./test.nix ];
+      common = [{
+        features = [ "k8s" ];
+        options = {
+          kubernetes.version = "1.24";
+        };
+      }];
     };
   };
 }

docs/content/examples/testing/test.nix

@@ -1,11 +1,5 @@
-{
-  lib,
-  pkgs,
-  kubenix,
-  test,
-  ...
-}: {
-  imports = [kubenix.modules.test];
+{ kubenix, test, ... }: {
+  imports = [ kubenix.modules.test ];
 
   test = {
     name = "example";