From 92fba41caf9aae6db47a6de1c273dbdc5e787c85 Mon Sep 17 00:00:00 2001
From: Antonio Gurgel <antonio@goorzhel.com>
Date: Tue, 28 Nov 2023 21:38:42 -0800
Subject: [PATCH] Write about trees

---
 README.rst | 77 +++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 59 insertions(+), 18 deletions(-)

diff --git a/README.rst b/README.rst
index 0742a90..9bad4e2 100644
--- a/README.rst
+++ b/README.rst
@@ -38,7 +38,7 @@ Usage
 Getting started
 ===============
 
-Add this flake to your flake's inputs, along with ``nixpkgs`` and `flake-utils``::
+Add this flake to your flake's inputs, along with ``nixpkgs`` and ``flake-utils``::
 
   {
     inputs = {
@@ -55,7 +55,7 @@ Add this flake to your flake's inputs, along with ``nixpkgs`` and `flake-utils``
 
 Next, split your flake's output into two sections: 
 
-#. One that "rakes" your module data into a tree (nested attrset), which runs in pure Nix; and
+#. One running in pure Nix that "rakes" your module data into a *tree* (more on that later); and
 #. one that builds derivations from your module data, using your current system's ``nixpkgs``.
 
 In practice::
@@ -65,6 +65,7 @@ In practice::
     outputs = {self, nixpkgs, flake-utils, turboprop}: 
       let rake = turboprop.rake in
     {
+      # I'll explain the distinction in a later chapter
       systemServiceData = rake.leaves ./system;
       serviceData = rake.leaves ./services;
 
@@ -82,19 +83,18 @@ In practice::
       };
 
       turbo = turboprop.packages.${system};
-      # We'll get back to the rest of this
-      namespaces = {};
-      paths = {};
 
+      # We'll get back to this too
+      flakeBuilders = turbo.flakeBuilders {};
+      namespaces = <...>;
+      paths = <...>;
     in {
-      packages = {
-        default =
-          turbo.mkDerivation {
-            # This too
-          };
+      packages.default = turbo.mkDerivation {
+          # This too
         };
-      });
-    };
+      }
+    );
+  }
 
 Now set that aside for the time being.
 
@@ -112,6 +112,7 @@ This is a module that creates a *templated chart derivation*, namely of cert-man
           featureGates = "ExperimentalGatewayAPISupport=true";
           installCRDs = true;
           prometheus = {
+
             enabled = true;
             servicemonitor = {
               enabled = true;
@@ -134,24 +135,64 @@ This is a module that creates a *templated chart derivation*, namely of cert-man
 
 #. The module takes as input:
 
-  #. A tree (nested attrset) of *untemplated* chart derivations;
+  #. A tree of *untemplated* chart derivations;
   #. the Turboprop library; and
-  #. user data specific to your flake. If you have none, you may pass `{charts, lib...}` instead.
+  #. user data specific to your flake. You may `omit any of these`_ if they're not used.
 
 #. The module has the output signature ``{builder, args, extraObjects}``.
 
-  #. ``builder`` is the Turboprop builder that will create your derivation. Most often, you will use ``helmChart``; other builders exist for scenarios such as deploying a `collection of Kubernetes objects`_ or a `single remote YAML file`_. You may even define your own builder.
+  #. ``builder`` is the Turboprop builder that will create your derivation. Most often, you will use ``helmChart``; other builders exist for scenarios such as deploying a `collection of Kubernetes objects`_ or a `single remote YAML file`_. You may even `define your own builder`_.
   #. ``args`` are arguments passed to the builder. Refer to each builder's signature below.
   #. ``extraObjects`` are objects to deploy alongside the chart.
 
-.. _collection of Kubernetes objects:
-.. _single remote YAML file:
-.. _define your own builder:
+.. _omit any of these: https://git.sr.ht/~goorzhel/kubernetes/tree/f3cba6831621288228581b7ad7b6762d6d58a966/item/system/gateway-system/gateway-api/default.nix#L1
+.. _collection of Kubernetes objects: https://git.sr.ht/~goorzhel/kubernetes/tree/f3cba6831621288228581b7ad7b6762d6d58a966/item/services/svc/gateway/default.nix#L12
+.. _single remote YAML file: https://git.sr.ht/~goorzhel/kubernetes/tree/f3cba6831621288228581b7ad7b6762d6d58a966/item/system/gateway-system/gateway-api/default.nix#L2
+.. _define your own builder: https://git.sr.ht/~goorzhel/kubernetes/tree/f3cba6831621288228581b7ad7b6762d6d58a966/item/services/svc/breezewiki/default.nix#L6
 
+=======================
+Tree of service modules
+=======================
 
+Turboprop's main operating concept is a *tree* of Nix modules, both in the filesystem sense (nested directories) and the Nix sense (nested attrsets). A service tree, then, consists of
+
+#. an arbitrarily-named root, such as ``./services``, which contains
+#. directories representing Kubernetes namespaces, which each contain
+#. Nix modules representing a templated deployment.
+
+This metaphor extends to charts, too. Both Turboprop and nixhelm, from which Turboprop borrows heavily, contain a chart tree:
+
+#. an arbitrarily-named root, ``./charts``, which contains
+#. directories representing Helm repositories, which each contain
+#. Nix modules representing a(n untemplated) chart.
+
+In practice::
+
+  $ nix run nixpkgs#tree -- ~/src/kubernetes/{chart,service}s --noreport
+  /home/ag/src/kubernetes/charts
+  ├── kubernetes-dashboard
+  │   └── kubernetes-dashboard
+  │       └── default.nix
+  <...>
+  /home/ag/src/kubernetes/services
+  <...>
+  ├── istio-system
+  │   ├── 1-18-1
+  │   │   └── default.nix
+  │   └── kiali
+  │       └── default.nix
+  └── svc
+      ├── breezewiki
+      │   └── default.nix
+      <...>
+      └── syncthing
+          └── default.nix
+
+You may have noticed that, if neither Nixhelm nor Turboprop provide a chart you need, you can supply your own. (PRs welcome, though.)
 
 #### flake builders
 
+
 ##### charts
 
 Signature, etc.