tree-wide: document most things

14 files changed, 252 insertions, 97 deletions

diff --git a/README.md b/README.md
index 5b4336f..03d0c1b 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# flake ❄️
+# ./. ❄️
 
 [![made with neovim](https://img.shields.io/static/v1?label=made%20with&message=neovim&color=00b952&style=flat-square&logo=neovim)](https://neovim.io/)
 [![nixos unstable](https://img.shields.io/static/v1?label=NixOS&message=unstable&color=5277c3&style=flat-square&logo=nixos)](https://nixos.org/)
@@ -6,47 +6,41 @@
 
 greasy taco i love
 
-## my machines
+## dev/
 
-all of these names are based off the [portal](<https://en.wikipedia.org/wiki/Portal_(video_game)>) series
+Tools that help me make and maintain everything
 
-### glados
+## lib/
 
-my main desktop
+Small functions I like to use around here
 
-### glados-wsl
+## modules/
 
-my main desktop, but the windows install :p
+Sets of modules meant for NixOS and
+[nix-darwin](https://github.com/LnL7/nix-darwin)
 
-### caroline
+## secrets/
 
-my macbook air
+Configuration secrets managed by the wonderful
+[agenix](https://github.com/ryantm/agenix)
 
-### atlas
+## users/
 
-my ampere arm server from oracle, services my miniflux instance and some other things.
+Home of my [home-manager](https://nix-community.github.io/home-manager/) user
+configurations
 
-## special thanks
+## ext/
 
-there are some amazing tools i use to make/manage this flake that i would highly recommend checking out:
+External, not so nix-y things
 
-- [home-manager](https://github.com/nix-community/home-manager)
-- [agenix](https://github.com/ryantm/agenix)
-- [cachix](https://www.cachix.org/)
-- [nix-fast-build](https://github.com/Mic92/nix-fast-build)
-- [nixinate](https://github.com/MatthewCroughan/nixinate)
-- [flake-parts](https://github.com/hercules-ci/flake-parts)
-- [terranix](https://github.com/terranix/terranix)
-- [lanzaboote](https://github.com/nix-community/lanzaboote)
-- [nixos-wsl](https://github.com/nix-community/nixos-wsl)
-- [nix-openwrt-imagebuilder](https://github.com/astro/nix-openwrt-imagebuilder)
+## .envrc
 
-## fun screenshots
+My [nix-direnv](https://github.com/nix-community/nix-direnv) configuration
 
-<details>
-<summary>click me!</summary>
+## flake.nix
 
-![gnome](https://user-images.githubusercontent.com/48872998/223897323-87f8d547-511b-48c3-a2e1-8ff22ac361e9.png)
-![neovim](https://user-images.githubusercontent.com/48872998/223897693-88eb0416-9ebc-45b6-837a-b28ada94336f.png)
+Where everything begins
 
-</details>
+## justfile
+
+Recipes to help me [just](https://github.com/casey/just) get things done
diff --git a/dev/README.md b/dev/README.md
new file mode 100644
index 0000000..f16f659
--- /dev/null
+++ b/dev/README.md
@@ -0,0 +1,14 @@
+# ./dev/
+
+## checks.nix
+
+Runs all of my favorite tools on the code here to make sure it's good to go
+
+## devShells.nix
+
+A misnomer - this only contains one shell
+
+## hydraJobs.nix
+
+Jobs I want to run in CI. Currently built by
+[`nix-fast-build`](https://github.com/Mic92/nix-fast-build)
diff --git a/ext/README.md b/ext/README.md
new file mode 100644
index 0000000..58cd24e
--- /dev/null
+++ b/ext/README.md
@@ -0,0 +1,11 @@
+# ./ext/
+
+## openwrt.nix 
+
+[OpenWrt](https://openwrt.org/) images generated via
+[nix-openwrt-imagebuilder](https://github.com/astro/nix-openwrt-imagebuilder)
+
+## terranix/
+
+[Terranix](https://terranix.org/index.html) configuration deployed via
+[OpenTofu](https://opentofu.org/)
diff --git a/flake.nix b/flake.nix
index 0982525..3a9c882 100644
--- a/flake.nix
+++ b/flake.nix
@@ -17,14 +17,13 @@
       ];
 
       imports = [
-        # primary outputs
         ./dev
         ./lib
         ./modules
         ./systems
         ./users
 
-        ./ext # external, not so nix-y things
+        ./ext
       ];
     };
 
diff --git a/lib/README.md b/lib/README.md
new file mode 100644
index 0000000..bde1e94
--- /dev/null
+++ b/lib/README.md
@@ -0,0 +1,13 @@
+# ./lib/
+
+## lib.nix
+
+Top-level declaration of my functions
+
+## builders.nix
+
+Wrappers around configurations builders such as `nixosSystem` and `darwinSystem`
+
+## nginx.nix
+
+Small helpers to avoid boilerplate in the `services.nginx` module
diff --git a/lib/builders.nix b/lib/builders.nix
new file mode 100644
index 0000000..6669c2d
--- /dev/null
+++ b/lib/builders.nix
@@ -0,0 +1,75 @@
+{
+  lib,
+  inputs,
+  self,
+}:
+let
+  # function -> function -> { } -> { }
+  # wrap the `args` applied to `builder` with the result of `apply`
+  # applied to those `args`
+  wrapBuilderWith =
+    apply: builder: args:
+    builder (apply args);
+
+  # string -> function -> { } -> { }
+  # wrap the `args` for `builder` of type `type` with nice defaults
+  wrapBuilder =
+    type:
+    wrapBuilderWith (
+      {
+        modules ? [ ],
+        specialArgs ? { },
+        ...
+      }@args:
+      args
+      // {
+        modules = modules ++ lib.attrValues (self."${type}Modules" or { });
+
+        specialArgs = specialArgs // {
+          inherit inputs;
+        };
+      }
+    );
+
+  # function -> { } -> { }
+  # wrap the `args` to the nixos `builder` function with nice defaults
+  wrapNixOS = builder: args: wrapBuilder "nixos" builder args;
+  # function -> { } -> { }
+  # wrap the `args` to the darwin `builder` function with nice defaults
+  wrapDarwin = builder: args: wrapBuilder "darwin" builder args;
+
+  # function -> { } -> { }
+  # wrap the `args` to the homeManager `builder` function with nice defaults
+  wrapUser =
+    builder: args:
+    wrapBuilderWith (
+      {
+        modules ? [ ],
+        extraSpecialArgs ? { },
+        ...
+      }@args:
+      args
+      // {
+        modules = modules ++ lib.attrValues (self.homeManagerModules or { });
+
+        extraSpecialArgs = extraSpecialArgs // {
+          inherit inputs;
+        };
+      }
+    ) builder args;
+in
+{
+
+  # { } -> { }
+  # apply nice defaults to the `args` of `nixosSystem`
+  nixosSystem = wrapNixOS inputs.nixpkgs.lib.nixosSystem;
+  # { } -> { }
+  # apply nice defaults to the `args` of (stable) `nixosSystem`
+  nixosSystemStable = wrapNixOS inputs.nixpkgs-stable.lib.nixosSystem;
+  # { } -> { }
+  # apply nice defaults to the `args` of `darwinSystem`
+  darwinSystem = wrapDarwin inputs.nix-darwin.lib.darwinSystem;
+  # { } -> { }
+  # apply nice defaults to the `args` of `homeManagerConfiguration`
+  homeManagerConfiguration = wrapUser inputs.home-manager.lib.homeManagerConfiguration;
+}
diff --git a/lib/lib.nix b/lib/lib.nix
index 1dea9be..54d6712 100644
--- a/lib/lib.nix
+++ b/lib/lib.nix
@@ -1,76 +1,20 @@
 {
   lib,
-  self,
   inputs,
+  self,
 }:
 let
-  # function -> function -> { } -> { }
-  # wrap the `args` applied to `builder` with the result of `apply`
-  # applied to those `args`
-  wrapBuilderWith =
-    apply: builder: args:
-    builder (apply args);
-
-  # string -> function -> { } -> { }
-  # wrap the `args` for `builder` of type `type` with nice defaults
-  wrapBuilder =
-    type:
-    wrapBuilderWith (
-      {
-        modules ? [ ],
-        specialArgs ? { },
-        ...
-      }@args:
-      args
-      // {
-        modules = modules ++ lib.attrValues (self."${type}Modules" or { });
-
-        specialArgs = specialArgs // {
-          inherit inputs;
-        };
-      }
-    );
-
-  # function -> { } -> { }
-  # wrap the `args` to the nixos `builder` function with nice defaults
-  wrapNixOS = builder: args: wrapBuilder "nixos" builder args;
-  # function -> { } -> { }
-  # wrap the `args` to the darwin `builder` function with nice defaults
-  wrapDarwin = builder: args: wrapBuilder "darwin" builder args;
-
-  # function -> { } -> { }
-  # wrap the `args` to the homeManager `builder` function with nice defaults
-  wrapUser =
-    builder: args:
-    wrapBuilderWith (
-      {
-        modules ? [ ],
-        extraSpecialArgs ? { },
-        ...
-      }@args:
-      args
-      // {
-        modules = modules ++ lib.attrValues (self.homeManagerModules or { });
-
-        extraSpecialArgs = extraSpecialArgs // {
-          inherit inputs;
-        };
-      }
-    ) builder args;
+  builders = import ./builders.nix { inherit lib inputs self; };
 in
 {
-  # { } -> { }
-  # apply nice defaults to the `args` of `nixosSystem`
-  nixosSystem = wrapNixOS inputs.nixpkgs.lib.nixosSystem;
-  # { } -> { }
-  # apply nice defaults to the `args` of (stable) `nixosSystem`
-  nixosSystemStable = wrapNixOS inputs.nixpkgs-stable.lib.nixosSystem;
-  # { } -> { }
-  # apply nice defaults to the `args` of `darwinSystem`
-  darwinSystem = wrapDarwin inputs.nix-darwin.lib.darwinSystem;
-  # { } -> { }
-  # apply nice defaults to the `args` of `homeManagerConfiguration`
-  homeManagerConfiguration = wrapUser inputs.home-manager.lib.homeManagerConfiguration;
+  inherit builders;
+
+  inherit (builders)
+    nixosSystem
+    nixosSystemStable
+    darwinSystem
+    homeManagerConfiguration
+    ;
 
   nginx = import ./nginx.nix lib;
 }
diff --git a/modules/README.md b/modules/README.md
new file mode 100644
index 0000000..7e45a1f
--- /dev/null
+++ b/modules/README.md
@@ -0,0 +1,6 @@
+# ./modules/
+
+These directory names are probably self explanatory
+
+In case they aren't: `darwin/` contains nix-darwin modules, `nixos/` contains
+NixOS modules, and `shared` contains modules I use on both!
diff --git a/modules/darwin/README.md b/modules/darwin/README.md
new file mode 100644
index 0000000..249286c
--- /dev/null
+++ b/modules/darwin/README.md
@@ -0,0 +1,17 @@
+# ./modules/darwin/
+
+## archetypes
+
+The high-level "type" of a machine (i.e., `personal` or `server`)
+
+## base
+
+Low level options shared for (almost) any kind of system
+
+## desktop
+
+Installs cool GUI stuff for desktops...or laptops too I guess
+
+## traits
+
+Small, reusable aspects of a machine - like users
diff --git a/modules/nixos/README.md b/modules/nixos/README.md
new file mode 100644
index 0000000..5a78133
--- /dev/null
+++ b/modules/nixos/README.md
@@ -0,0 +1,21 @@
+# ./modules/nixos/
+
+## archetypes
+
+The high-level "type" of a machine (i.e., `personal` or `server`)
+
+## base
+
+Low level options shared for (almost) any kind of system
+
+## desktop
+
+Installs cool GUI stuff for desktops...or laptops too I guess
+
+## server
+
+Installs cool daemons and such for servers
+
+## traits
+
+Small, reusable aspects of a machine - like users
diff --git a/modules/shared/README.md b/modules/shared/README.md
new file mode 100644
index 0000000..9228717
--- /dev/null
+++ b/modules/shared/README.md
@@ -0,0 +1,9 @@
+# ./modules/shared/
+
+## base
+
+Low level options shared for (almost) any kind of system
+
+## traits
+
+Small, reusable aspects of a machine - like users
diff --git a/secrets/README.md b/secrets/README.md
new file mode 100644
index 0000000..a7c75ad
--- /dev/null
+++ b/secrets/README.md
@@ -0,0 +1,14 @@
+# ./secrets/
+
+## */
+
+Each directory is named after the system the secrets inside of it are meant for
+
+## secrets.nix
+
+agenix's
+[secrets.nix](https://github.com/ryantm/agenix/blob/3a56735779db467538fb2e577eda28a9daacaca6/README.md#tutorial)
+
+## toSecrets.nix
+
+A function that helps structure the `secrets.nix` configuration
diff --git a/systems/README.md b/systems/README.md
new file mode 100644
index 0000000..8a399f8
--- /dev/null
+++ b/systems/README.md
@@ -0,0 +1,33 @@
+# ./systems/
+
+All of these names are based off the
+[Portal](<https://en.wikipedia.org/wiki/Portal_(video_game)>) series
+
+## glados/
+
+Main desktop
+
+## glados-wsl/
+
+Main desktop, but the windows install :p
+
+## caroline/
+
+2017 MacBook Air
+
+## atlas/
+
+Ampere ARM server from Oracle, services my [Miniflux](https://miniflux.app/)
+instance and some other things.
+
+## darwin.nix
+
+Declarations of nix-darwin systems
+
+## nixos.nix
+
+Declarations of NixOS systems
+
+## nixinate.nix
+
+Apps to deploy the above systems through [nixinate](https://github.com/MatthewCroughan/nixinate)
diff --git a/users/README.md b/users/README.md
new file mode 100644
index 0000000..d1b1b5b
--- /dev/null
+++ b/users/README.md
@@ -0,0 +1,5 @@
+# ./users/
+
+## seth/
+
+Me! (getchoo)