add *some* documentation

4 files changed, 129 insertions, 0 deletions

diff --git a/doc/book.toml b/doc/book.toml
new file mode 100644
index 0000000..bb3ccc2
--- /dev/null
+++ b/doc/book.toml
@@ -0,0 +1,2 @@
+[book]
+title = "dewclaw documentation"
diff --git a/doc/default.nix b/doc/default.nix
new file mode 100644
index 0000000..95b9dea
--- /dev/null
+++ b/doc/default.nix
@@ -0,0 +1,47 @@
+{ pkgs ? import <nixpkgs> { config = {}; overlays = []; }
+}:
+
+let
+  evaluated = pkgs.lib.evalModules {
+    modules = [
+      ../openwrt
+    ];
+    specialArgs = {
+      inherit pkgs;
+    };
+  };
+
+  optionsDoc = pkgs.nixosOptionsDoc {
+    inherit (evaluated) options;
+    transformOptions = opt:
+      let
+        cwd = toString ../.;
+        shorten = decl:
+          let
+            removed = pkgs.lib.removePrefix cwd decl;
+          in
+            if removed != decl
+            then {
+              url =
+                "https://git.eno.space/dewclaw.git/tree${removed}"
+                + (if pkgs.lib.hasSuffix ".nix" removed
+                   then ""
+                   else "/default.nix");
+              name = "<dewclaw${removed}>";
+            }
+            else removed;
+        in
+          opt // { declarations = map shorten opt.declarations; };
+  };
+in
+
+pkgs.runCommand "dewclaw-book" {
+  src = ./src;
+  buildInputs = [ pkgs.mdbook ];
+} ''
+  cp -r --no-preserve=all $src ./src
+  ln -s ${optionsDoc.optionsCommonMark} ./src/options.md
+  ln -s ${../README.md} ./src/README.md
+  mdbook build
+  mv book $out
+''
diff --git a/doc/src/SUMMARY.md b/doc/src/SUMMARY.md
new file mode 100644
index 0000000..2040fd3
--- /dev/null
+++ b/doc/src/SUMMARY.md
@@ -0,0 +1,6 @@
+# Summary
+
+[But why?](./README.md)
+
+- [How to use this](./how-to.md)
+- [Options documentation](./options.md)
diff --git a/doc/src/how-to.md b/doc/src/how-to.md
new file mode 100644
index 0000000..a78f3c5
--- /dev/null
+++ b/doc/src/how-to.md
@@ -0,0 +1,74 @@
+# How to use
+
+dewclaw can declaratively manage some (but by far not all) aspects of OpenWRT devices.
+Packages can be installed (and subsequently removed) declaratively by listing them in the `packages` option.
+UCI configs can be set declaratively using the `uci.settings` hierarchy, or be marked for imperative configuration by adding the appropriate package names to `uci.retain`.
+Files in `/etc` can be create with the `etc` hierarchy.
+
+## Mapping UCI options
+
+Mapping existing UCI configurations to `uci.settings` values is straight-forward starting with the output of `uci show`. UCI outputs its configuration in a specific format:
+```
+package.namedSection=type1
+package.namedSection.option='value'
+package.namedSection.list='value1' 'value2' ...
+package.@anonSection=type2
+package.@anonSection.option='value'
+```
+
+In dewclaw `package` is the top level of keys in `uci.settings`, `type` is the second level, and below the `type` level we either have a third `namedSection` level or a list of `anonSection`s.
+Each named or anonymous section is itself a set of `option = value` assignments.
+dewclaw cannot mix named and anonymous sections, any given type must be configured entirely with named sections or entirely with unnamed sections.
+
+The example `uci show` output above would thus map to the following dewclaw device configuration:
+```nix
+openwrt.router.uci.settings = {
+  package.type1 = {
+    namedSection = {
+      option = "value";
+      list = [ "value1" "value2" ];
+    };
+  };
+
+  package.type2 = [
+    {
+      option = "value";
+    }
+  ];
+}
+```
+
+Option values may be any UCI-compatible type: strings, paths and integers are passed through, booleans are converted to `0/1`.
+Additionally there is support for secret values, with a [sops] secrets backend built into dewclaw directly.
+Secrets are loaded from a backend during deployment time and will be interpolated into the generated UCI config.
+To load an option value from a secret, set `option._secret = "secretName"` in `uci.settings`.
+
+## Building a configuration
+
+Once a configuration for any number of devices is written it can be passed to dewclaw and built into a set of deployment scripts:
+```nix
+{ pkgs ? import <nixpkgs> {} }:
+
+import <dewclaw> {
+  inherit pkgs;
+  configuration = ./config.nix;
+}
+```
+
+All `openwrt` device configurations listed in `config.nix` will be built, each producing a stand-alone deployment script, and provided in a single nix output.
+
+## Deploying a configuration
+
+Building the provided example produces an output with a single deployment script, `deploy-example`, that can be run without arguments to deploy to the assigned target and reboot the device.
+The deployment process on the device will take a snapshot of the current device configuration, apply changes as needed to satisfy the new configuration, and wait for confirmation that the new configuration is acceptable.
+The deployment script provides this confirmation by reconnecting to the device after it has rebooted, if this reconnection succeeds the configuration is accepted.
+
+After a reboot the device will wait for a set amount of time before automatically rolling back to the previous configuration.
+
+### Reload-only deployment
+
+Deploy scripts also accept a `--reload` argument to instruct the device to only reload UCI configuration instead of rebooting.
+This is faster and less disruptive but may have unintended side-effects on services that are not properly configured by OpenWRT's `reload_config` and should thus be used with care.
+Despite not rebooting to apply the configuration this mode also takes a snapshot and performs a rollback if no confirmation is provided.
+
+[sops]: https://github.com/getsops/sops