better docs

.gitignore

@@ -0,0 +1,6 @@
+# Nix
+result
+result-*
+
+# Don't keep the example lockfile around
+/example/flake.lock

README.md

@@ -1,6 +1,6 @@
 # flake-utils
 
-**STATUS: WIP**
+**STATUS: alpha**
 
 Pure Nix flake utility functions.
 
@@ -10,31 +10,54 @@ flakes.
 
 ## Usage
 
-`flake.nix`
+### `defaultSystems -> [<system>]`
+
+A list of all the systems supported by the nixpkgs project.
+
+### `eachSystem -> [<system>] -> (<system> -> attrs)`
+
+A common case is to build the same structure for each system. Instead of
+building the hierarchy manually or per prefix, iterate over each systems and
+then re-build the hierarchy.
+
+Eg:
+
+```nix
+eachSystem ["x86-64-linux"] (system: { hello = 42; })
+# => { hello.x86-64-linux.hello = 42; }
+```
+
+### `eachDefaultSystem -> (<system> -> attrs)`
+
+`eachSystem` pre-populated with `defaultSystems`.
+
+### `mkApp { drv, name ? drv.pname or drv.name, execPath ? drv.passthru.execPath or "/bin/${name}"`
+
+A small utility that builds the structure expected by the special `apps` and `defaultApp` prefixes.
+
+## Example
+
+Here is how it looks like in practice:
+
+[$ example/flake.nix](example/flake.nix) as nix
 ```nix
 {
+  description = "Flake utils demo";
   edition = 201909;
-  description = "My flake";
+
-  inputs = {
+  inputs.utils = {
-    utils = { type = "github"; owner = "numtide"; repo = "flake-utils"; };
+    uri = "github:numtide/flake-utils";
   };
+
   outputs = { self, nixpkgs, utils }:
-    utils.eachDefaultSystem (system:
+    utils.lib.eachDefaultSystem (system:
       let pkgs = nixpkgs.legacyPackages.${system}; in
       rec {
-        packages = {
+        packages.hello = pkgs.hello;
-          my-app = pkgs.callPackage ./my-app.nix {};
+        defaultPackage = packages.hello;
-        };
+        apps.hello = utils.lib.mkApp { drv = packages.hello; };
-
+        defaultApp = apps.hello;
-        defaultPackage = package.my-app;
+      }
-
-        apps = {
-          my-app = flake.mkApp packages.my-app;
-        };
-
-        defaultApp = apps.my-app;
-      };
     );
 }
 ```
-

example/flake.nix

@@ -3,8 +3,7 @@
   edition = 201909;
 
   inputs.utils = {
-    type = "git";
+    uri = "github:numtide/flake-utils";
-    uri = "file:///home/zimbatm/go/src/github.com/zimbatm/flake-utils";
   };
 
   outputs = { self, nixpkgs, utils }: