docs: document new lib functions & usage

docs/examples.md

@@ -1,4 +1,6 @@
 # Example Configs
 
+- [nixtest itself](https://gitlab.com/TECHNOFAB/nixtest)
+    see `flake.nix` and `tests/`
 - [TECHNOFAB/nix-gitlab-ci](https://gitlab.com/TECHNOFAB/nix-gitlab-ci)
-    see tests/
+    see `tests/`

docs/reference.md

@@ -0,0 +1,53 @@
+# Reference
+
+## `flakeModule`
+
+The `flakeModule` for [flake-parts](https://flake.parts).
+
+## `lib`
+
+### `module`
+
+The nix module for validation of inputs etc.
+Used internally by `mkNixtestConfig`.
+
+### `autodiscover`
+
+```nix
+autodiscover {
+  dir,
+  pattern ? ".*_test.nix",
+}
+```
+
+Finds all test files in `dir` matching `pattern`.
+Returns a list of modules (can be passed to `mkNixtest`'s `modules` arg).
+
+### `mkNixtestConfig`
+
+```nix
+mkNixtestConfig {
+  modules,
+  args ? {},
+}
+```
+
+Evaluates the test `modules`.
+`args` are passed to the modules using `_module.args = args`.
+
+**Noteworthy attributes**:
+
+- `app`: nixtest wrapper
+- `finalConfigJson`: derivation containing the tests json file
+
+### `mkNixtest`
+
+```nix
+mkNixtest {
+  modules,
+  args ? {},
+}
+```
+
+Creates the nixtest wrapper, using the tests in `modules`.
+Basically `(mkNixtestConfig <arguments>).app`.

docs/usage.md

@@ -2,6 +2,9 @@
 
 ## Flake Module
 
+The easiest way to use Nixtest is probably using the flakeModule.
+Just import `nixtest.flakeModule`, then define suites and tests in `perSystem`:
+
 ```nix
 {
   inputs.nixtest.url = "gitlab:TECHNOFAB/nixtest?dir=lib";
@@ -34,10 +37,25 @@
 
 ## Library
 
-You can also integrate nixtest in your own workflow by using the lib functions directly.
+You can also use the lib directly, like this for example:
-Check out `flakeModule.nix` to see how it's used there.
 
-<!-- TODO: more detailed? -->
+```nix
+packages.tests = ntlib.mkNixtest {
+  modules = ntlib.autodiscover {dir = ./tests;};
+  args = {
+    inherit pkgs ntlib;
+  };
+};
+```
+
+This will auto-discover all test files ending with `_test.nix`.
+See [reference](reference.md) for all params to `autodiscover`.
+
+`ntlib` can be defined like this:
+
+```nix
+ntlib = inputs.nixtests.lib {inherit pkgs;};
+```
 
 ## Define Tests
 
@@ -84,9 +102,17 @@ Examples:
     # to make it more reproducible and cleaner, use --pure to switch to pure
     # mode which will unset all env variables before running the test. That 
     # requires you to set PATH yourself then:
+    # 
+    # ''
+    #  export PATH="${lib.makeBinPath [pkgs.gnugrep]}"
+    #  grep -q "test" ${builtins.toFile "test" "test"}
+    # '';
+    #
+    # you can also use the helpers to make it nicer to read:
     ''
-      export PATH="${lib.makeBinPath [pkgs.gnugrep]}"
+      ${ntlib.helpers.path [pkgs.gnugrep]}
-      grep -q "test" ${builtins.toFile "test" "test"}
+      ${ntlib.helpers.scriptHelpers}  # this adds helpers like assert etc.
+      assert_file_contains ${builtins.toFile "test" "test"} "test" "file should contain 'test'"
     '';
   }
   {
@@ -102,3 +128,7 @@ Examples:
   }
 ]
 ```
+
+!!! note
+
+    for more examples see [examples](./examples.md)

flake.nix

@@ -106,11 +106,13 @@
             nav = [
               {"Introduction" = "index.md";}
               {"Usage" = "usage.md";}
+              {"Reference" = "reference.md";}
               {"CLI" = "cli.md";}
               {"Example Configs" = "examples.md";}
             ];
             markdown_extensions = [
               "pymdownx.superfences"
+              "admonition"
             ];
             extra.analytics = {
               provider = "umami";

lib/testHelpers.nix

@@ -2,6 +2,6 @@
   path = pkgs: "export PATH=${lib.makeBinPath pkgs}";
   pathAdd = pkgs: "export PATH=$PATH:${lib.makeBinPath pkgs}";
   scriptHelpers = builtins.readFile ./scriptHelpers.sh;
-  toJsonFile = any: builtins.toFile "actual" (builtins.toJSON any);
+  toJsonFile = any: builtins.toFile "actual" (builtins.unsafeDiscardStringContext (builtins.toJSON any));
   toPrettyFile = any: builtins.toFile "actual" (lib.generators.toPretty {} any);
 }