docs: move help for lib to mdbook

README.md

@@ -19,39 +19,24 @@ The project supports semantic versioning, so we advise to pin the major version
 }
 ```
 
-Flocken currently provides the following attributes:
+## [`flocken.lib`](https://mirkolenz.github.io/lib.html)
 
-### [`flocken.lib`](./lib/default.nix)
+A collection of utility functions for nix flakes.
+See the documentation for more details.
 
-- `getModules DIRECTORY`: Get all modules in a directory.
-  Can for instance be used to automatically import all modules in a directory.
-  Directories containing a `default.nix` file are considered modules.
-  Paths starting with `_` are ignored.
-- `optionalPath PATH`: Get a path as a list if it exists.
-  Returns an empty list if the path does not exist.
-  Useful for adding optional paths to import statements.
-- `isEmpty VALUE`: Check if a value of arbitrary type is empty.
-- `isNonEmpty VALUE`: Check if a value of arbitrary type is non-empty.
-- `isEnabled ATTRS`: Checks if an attrset has a key with the name `enable` set to `true`.
-- `githubSshKeys {user, sha256}`: Returns a list of GitHub SSH keys for a user.
-- `getLeaves ATTRS`: Get all leaves of an attrset.
-- `attrByDottedPath PATH DEFAULT ATTRS`: Return an attribute from nested attribute sets.
-- `getAttrFromDottedPath PATH ATTRS`: Like `attrByDottedPath`, but without a default value. If it doesn't find the path it will throw an error.
-- `setAttrByDottedPath PATH VALUE`: Create a new attribute set with value set at the nested attribute location specified in PATH.
-
-### [`flocken.legacyPackages.${system}.mkDockerManifest`](./docs/docker-manifest.md)
+## [`flocken.legacyPackages.${system}.mkDockerManifest`](https://mirkolenz.github.io/docker-manifest.html)
 
 Create and push a Docker manifest to a registry.
 This is particularly useful for multi-arch images.
 Some arguments (e.g., `version`) differ between invocations and thus need to be provided in a dynamic fashion.
 We recommend to use environment variables for this purpose.
-For instance, when running in a GitHub action, you only have to provide a value for `VERSION` and `GH_TOKEN` and then can use the following snippet:
+For instance, when running in a GitHub action, you only have to provide a value for `VERSION` and `GITHUB_TOKEN` and then can use the following snippet:
 
 ```nix
 docker-manifest = mkDockerManifest {
   github = {
     enable = true;
-    token = "$GH_TOKEN";
+    token = "$GITHUB_TOKEN";
   };
   version = builtins.getEnv "VERSION";
   imageStreams = with self.packages; [x86_64-linux.docker aarch64-linux.docker];
@@ -88,5 +73,5 @@ jobs:
       - run: nix run --impure .#docker-manifest
         env:
           VERSION: "1.0.0"
-          GH_TOKEN: ${{ github.token }}
+          GITHUB_TOKEN: ${{ github.token }}
 ```

docs/book.nix

@@ -2,13 +2,17 @@
   lib,
   stdenvNoCC,
   mdbook,
+  nixdoc,
   writeShellApplication,
   python3,
   dockerManifestMarkdown,
 }:
 stdenvNoCC.mkDerivation (finalAttrs: {
   name = "book";
-  nativeBuildInputs = [ mdbook ];
+  nativeBuildInputs = [
+    mdbook
+    nixdoc
+  ];
   src = lib.fileset.toSource {
     root = ./.;
     fileset = lib.fileset.unions [
@@ -21,6 +25,11 @@ stdenvNoCC.mkDerivation (finalAttrs: {
 
     ln -s ${dockerManifestMarkdown} src/docker-manifest.md
     ln -s ${../README.md} src/README.md
+    nixdoc \
+      --category "" \
+      --description "" \
+      --prefix "" \
+      --file ${../lib/default.nix} > src/lib.md
     mdbook build
 
     runHook postBuild

docs/src/SUMMARY.md

@@ -2,4 +2,6 @@
 
 [Introduction](README.md)
 
+[lib](lib.md)
+
 [mkDockerManifest](docker-manifest.md)

lib/default.nix

@@ -1,4 +1,31 @@
 lib: rec {
+  /**
+    Get all modules in a directory.
+    Can for instance be used to automatically import all modules in a directory.
+    Directories containing a `default.nix` file are considered modules.
+    Paths starting with `_` are ignored.
+
+    # Inputs
+
+    `dir`
+    : The directory to search for modules in.
+
+    # Type
+
+    ```
+    getModules :: Path -> [ Path ]
+    ```
+
+    # Examples
+
+    ```nix
+    getModules ./.
+    => [
+      ./module1
+      ./module2
+    ]
+    ```
+  */
   getModules =
     dir:
     let
@@ -17,10 +44,150 @@ lib: rec {
       filteredPaths = builtins.attrNames filteredContents;
     in
     builtins.map mkImport filteredPaths;
+
+  /**
+    Get a path as a list if it exists.
+    Returns an empty list if the path does not exist.
+    Useful for adding optional paths to import statements.
+
+    # Inputs
+
+    `path`
+    : The path to check for existence.
+
+    # Type
+
+    ```
+    optionalPath :: Path -> [ Path ]
+    ```
+
+    # Examples
+
+    ```nix
+    optionalPath ./module.nix
+    => [ ./module.nix ]
+    optionalPath ./non-existing-module.nix
+    => [ ]
+    ```
+  */
   optionalPath = path: if builtins.pathExists path then [ path ] else [ ];
+
+  /**
+    Check if a value of arbitrary type is empty.
+
+    # Inputs
+
+    `value`
+    : The value to check for emptiness.
+
+    # Type
+
+    ```
+    isEmpty :: Any -> Bool
+    ```
+
+    # Examples
+
+    ```nix
+    isEmpty ""
+    => true
+    isEmpty null
+    => true
+    isEmpty [ ]
+    => true
+    isEmpty { }
+    => true
+    isEmpty "foo"
+    => false
+    isEmpty [ "foo" ]
+    => false
+    isEmpty { foo = "bar"; }
+    => false
+    ```
+  */
   isEmpty = value: value == null || value == "" || value == [ ] || value == { };
+
+  /**
+    Check if a value of arbitrary type is non-empty.
+    Opposite of `isEmpty`.
+
+    # Inputs
+
+    `value`
+    : The value to check for non-emptiness.
+
+    # Type
+
+    ```
+    isNotEmpty :: Any -> Bool
+    ```
+
+    # Examples
+
+    ```nix
+    isNotEmpty ""
+    => false
+    ```
+  */
   isNotEmpty = value: !isEmpty value;
+
+  /**
+    Checks if an attrset has a key with the name `enable` set to `true`.
+
+    # Inputs
+
+    `x`
+    : The attrset to check.
+
+    # Type
+
+    ```
+    isEnabled :: { enable ? Bool } -> Bool
+    ```
+
+    # Examples
+
+    ```nix
+    isEnabled { enable = true; }
+    => true
+    isEnabled { enable = false; }
+    => false
+    isEnabled { }
+    => false
+    ```
+  */
   isEnabled = x: builtins.hasAttr "enable" x && x.enable == true;
+
+  /**
+    Returns a list of GitHub SSH keys for a user.
+
+    # Inputs
+
+    `user`
+    : The GitHub username to get the SSH keys for.
+
+    `sha256`
+    : The sha256 hash of the file.
+
+    # Type
+
+    ```
+    githubSshKeys :: { user: String, sha256: String } -> [ String ]
+    ```
+
+    # Examples
+
+    ```nix
+    githubSshKeys {
+      user = "mirkolenz";
+      sha256 = lib.fakeSha256;
+    }
+    => [
+      "ssh-rsa AAAA..."
+      "ssh-rsa AAAA..."
+    ]
+    ```
+  */
   githubSshKeys =
     {
       user,
@@ -34,6 +201,34 @@ lib: rec {
       parsedResponse = builtins.fromJSON (builtins.readFile apiResponse);
     in
     builtins.map (x: x.key) parsedResponse;
+
+  /**
+    Get all leaves of an attrset.
+
+    # Inputs
+
+    `attrs`
+    : The attrset to get the leaves of.
+
+    # Type
+
+    ```
+    getLeaves :: AttrSet -> AttrSet
+    ```
+
+    # Examples
+
+    ```nix
+    getLeaves {
+      foo = {
+        bar = "baz";
+      };
+    }
+    => {
+      "foo.bar" = "baz";
+    }
+    ```
+  */
   getLeaves =
     let
       getLeavesPath =
@@ -49,7 +244,86 @@ lib: rec {
           ];
     in
     attrs: builtins.listToAttrs (getLeavesPath attrs [ ]);
+
+  /**
+    Return an attribute from nested attribute sets.
+
+    # Inputs
+
+    `path`
+    : The path to the attribute.
+
+    `default`
+    : The default value to return if the attribute does not exist.
+
+    `set`
+    : The attribute set to get the attribute from.
+
+    # Type
+
+    ```
+    attrByPath :: String -> Any -> AttrSet -> Any
+    ```
+
+    # Examples
+
+    ```nix
+    attrByPath "foo.bar" "default" { foo = { bar = "baz"; }; }
+    => "baz"
+    ```
+  */
   attrByDottedPath = path: lib.attrByPath (lib.splitString "." path);
+
+  /**
+    Like `attrByDottedPath`, but without a default value.
+    If it doesn't find the path it will throw an error.
+
+    # Inputs
+
+    `path`
+    : The path to the attribute.
+
+    `set`
+    : The attribute set to get the attribute from.
+
+    # Type
+
+    ```
+    getAttrFromDottedPath :: String -> AttrSet -> Any
+    ```
+
+    # Examples
+
+    ```nix
+    getAttrFromDottedPath "foo.bar" { foo = { bar = "baz"; }; }
+    => "baz"
+    ```
+  */
   getAttrFromDottedPath = path: lib.getAttrFromPath (lib.splitString "." path);
+
+  /**
+    Create a new attribute set with value set at the nested attribute location specified in PATH.
+
+    # Inputs
+
+    `path`
+    : The path to the attribute.
+
+    `value`
+    : The value to set.
+
+    # Type
+
+    ```
+    setAttrByDottedPath :: String -> Any -> AttrSet
+    ```
+
+    # Examples
+
+    ```nix
+    setAttrByDottedPath "foo.bar" "baz"
+    => { foo = { bar = "baz"; }; }
+    ```
+  */
   setAttrByDottedPath = path: lib.setAttrByPath (lib.splitString "." path);
 }