docs/images/logo.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="240" height="240" fill="none"><rect width="240" height="240" fill="#fff" rx="27"/><path fill="#FC6D26" d="m120.7 159.2 46.4 37.5c3.3 2.6 6.6 4.6 11.2 4.6h1.3l3 5.3-6.2 10.8h-12.8l-20.8-36.2-30-.1-12.7-21.9h20.6Zm89.2 0-12.4 22h-3.8a25 25 0 0 0-.6-1.7v-.1l-8.4-20.2h25.2ZM41 178.2l-12.8-21.6L43 131H13.7l-6.3-10.9 6.4-11.1 41.8.1 15-25.9H96l-54.8 95ZM149 48l14.7-25.4h12.6l6.4 11-21 36.2 14.9 26-10.6 18.5-27.2-65.3c-2.2-6-8-9.7-14-9.6-2 0-3.8.3-5.5 1l-10.2-17.7 25.3-.3L149 48Z"/><path fill="url(#a)" d="m120.7 159.2 46.4 37.5c3.3 2.6 6.6 4.6 11.2 4.6h1.3l3 5.3-6.2 10.8h-12.8l-20.8-36.2-30-.1-12.7-21.9h20.6Zm89.2 0-12.4 22h-3.8a25 25 0 0 0-.6-1.7v-.1l-8.4-20.2h25.2ZM41 178.2l-12.8-21.6L43 131H13.7l-6.3-10.9 6.4-11.1 41.8.1 15-25.9H96l-54.8 95ZM149 48l14.7-25.4h12.6l6.4 11-21 36.2 14.9 26-10.6 18.5-27.2-65.3c-2.2-6-8-9.7-14-9.6-2 0-3.8.3-5.5 1l-10.2-17.7 25.3-.3L149 48Z"/><path fill="#E24329" d="m103.6 170 27.4 47.4-25.2.3L91 192l-14.7 25.4H63.9l-6.5-11 3.6-6.2h20l1.4-3.8 15-37.3 6.2 10.7Zm-25.3-43.8-10.6 25.4-4.2-7.2 12.6-22 2.2 3.8Zm133.4-42.8L197 109h29.3l6.3 10.9-6.4 11h-41.8l-6.7 11.5L167 117l31.8-55.2 12.8 21.7ZM97.1 58.6h9.3l-9 22H30l12.4-22H72L57.3 33.3l6.2-10.8h12.8l20.8 36.2Z"/><path fill="url(#b)" d="m103.6 170 27.4 47.4-25.2.3L91 192l-14.7 25.4H63.9l-6.5-11 3.6-6.2h20l1.4-3.8 15-37.3 6.2 10.7Zm-25.3-43.8-10.6 25.4-4.2-7.2 12.6-22 2.2 3.8Zm133.4-42.8L197 109h29.3l6.3 10.9-6.4 11h-41.8l-6.7 11.5L167 117l31.8-55.2 12.8 21.7ZM97.1 58.6h9.3l-9 22H30l12.4-22H72L57.3 33.3l6.2-10.8h12.8l20.8 36.2Z"/><path fill="#000" d="m106.8 119.6 53.3 42-35.4-87-18 45Zm81.6 66.3a9.7 9.7 0 0 1-10 9.4c-2.6 0-4.7-1-7.5-3.3l-70.4-56.8-23.6 59.1H56.4l59.7-143.2a9 9 0 0 1 8.7-5.8 8.6 8.6 0 0 1 8.4 5.8l54.3 130.6c.5 1.3 1 2.6 1 4v.2Z"/><defs><linearGradient id="a" x1="181.2" x2="141" y1="114.6" y2="45.1" gradientUnits="userSpaceOnUse"><stop stop-color="#699AD7"/><stop offset=".2" stop-color="#7EB1DD"/><stop offset="1" stop-color="#7EBAE4"/></linearGradient><linearGradient id="b" x1="151.1" x2="191.8" y1="167.7" y2="98.7" gradientUnits="userSpaceOnUse"><stop stop-color="#415E9A"/><stop offset=".2" stop-color="#4A6BAF"/><stop offset="1" stop-color="#5277C3"/></linearGradient></defs></svg>

docs/options.md

@@ -1,3 +0,0 @@
-# Options
-
-{% include 'options.md' %}

docs/reference.md

@@ -84,6 +84,132 @@ mkNixibleCli config
 Creates a CLI executable for your Nixible configuration.
 Basically `(mkNixible config).config.cli`.
 
-______________________________________________________________________
+## Configuration Options
 
-See [options](./options.md) for more.
+### `ansiblePackage`
+
+**Type:** `package`
+**Default:** Custom ansible-core package
+
+The Ansible package to use. The default package is optimized for size, by not
+including the gazillion collections that `pkgs.ansible` and `pkgs.ansible-core` include.
+
+```nix
+ansiblePackage = pkgs.ansible;
+```
+
+### `collections`
+
+**Type:** `attrsOf collectionType`
+**Default:** `{}`
+
+Ansible collections to fetch from Galaxy.
+
+```nix
+collections = {
+  "community-general" = {
+    version = "8.0.0";
+    hash = "sha256-...";
+  };
+};
+```
+
+### `dependencies`
+
+**Type:** `listOf package`
+**Default:** `[]`
+
+Additional packages available at runtime.
+
+```nix
+dependencies = [pkgs.git pkgs.rsync];
+```
+
+### `inventory`
+
+**Type:** `attrs`
+**Default:** `{}`
+
+Ansible inventory as Nix data structure, converted to JSON.
+
+```nix
+inventory = {
+  webservers = {
+    hosts = {
+      web1 = { ansible_host = "192.168.1.10"; };
+    };
+    vars = {
+      http_port = 80;
+    };
+  };
+};
+```
+
+### `playbook`
+
+**Type:** `listOf playbookType`
+
+List of plays that make up the playbook.
+
+```nix
+playbook = [
+  {
+    name = "Configure servers";
+    hosts = "webservers";
+    become = true;
+    tasks = [
+      {
+        name = "Install nginx";
+        package = {
+          name = "nginx";
+          state = "present";
+        };
+      }
+    ];
+  }
+];
+```
+
+## Collection Type
+
+### `version`
+
+**Type:** `str`
+
+Version of the collection from Ansible Galaxy.
+
+### `hash`
+
+**Type:** `str`
+
+SHA256 hash of the collection tarball for verification.
+
+## Playbook Type
+
+### `name`
+
+**Type:** `str`
+
+Name of the play.
+
+### `hosts`
+
+**Type:** `str`
+
+Target hosts pattern (e.g., "all", "webservers", "localhost").
+
+### `become`
+
+**Type:** `bool`
+**Default:** `false`
+
+Whether to use privilege escalation.
+
+### `tasks`
+
+**Type:** `listOf attrs`
+**Default:** `[]`
+
+List of tasks to execute. Each task corresponds to Ansible task syntax.
+
+Standard Ansible playbook options are supported: `gather_facts`, `serial`, `vars`, `vars_files`, `tags`, `handlers`, `pre_tasks`, `post_tasks`, etc.

docs/style.css

@@ -1,15 +0,0 @@
-.md-header__button.md-logo {
-  margin: 0;
-  padding-top: .2rem;
-  padding-bottom: .2rem;
-}
-
-[dir="ltr"] .md-header__title {
-  margin-left: 0;
-}
-
-.md-header__button.md-logo img,
-.md-header__button.md-logo svg {
-  height: 2rem;
-}
-

flake.lock

@@ -230,11 +230,11 @@
     "nix-mkdocs": {
       "locked": {
         "dir": "lib",
-        "lastModified": 1757055638,
+        "lastModified": 1745841841,
-        "narHash": "sha256-KHYSkEreFe4meXzSdEbknC/HwaQSNClQkc8vzHlAsMM=",
+        "narHash": "sha256-297zPQbUlc7ZAYDoaD6mCmQxCC3Tr4YOKekRF1ArZ7g=",
         "owner": "technofab",
         "repo": "nixmkdocs",
-        "rev": "7840a5febdbeaf2da90babf6c94b3d0929d2bf74",
+        "rev": "c7e3c3b13ded25818e9789938387bba6f2cde690",
         "type": "gitlab"
       },
       "original": {

flake.nix

@@ -17,7 +17,6 @@
       perSystem = {
         lib,
         pkgs,
-        self',
         config,
         ...
       }: {
@@ -39,47 +38,80 @@
             convco.enable = true;
           };
         };
-        docs."default".config = {
+        doc = {
           path = ./docs;
-          material = {
+          deps = pp: [
-            enable = true;
+            pp.mkdocs-material
-            colors = {
+            (pp.callPackage inputs.mkdocs-material-umami {})
-              primary = "black";
+          ];
-              accent = "blue";
-            };
-            umami = {
-              enable = true;
-              src = "https://analytics.tf/umami";
-              siteId = "d8354dfa-2ad2-4089-90d2-899b981aef22";
-              domains = ["nixible.projects.tf"];
-            };
-          };
-          macros = {
-            enable = true;
-            includeDir = toString self'.packages.optionsDocs;
-          };
           config = {
             site_name = "Nixible";
-            site_url = "https://nixible.projects.tf";
             repo_name = "TECHNOFAB/nixible";
             repo_url = "https://gitlab.com/TECHNOFAB/nixible";
-            extra_css = ["style.css"];
+            edit_uri = "edit/main/docs/";
             theme = {
+              name = "material";
+              features = ["content.code.copy" "content.action.edit"];
               icon.repo = "simple/gitlab";
-              logo = "images/logo.svg";
+              logo = "images/logo.png";
-              favicon = "images/logo.svg";
+              favicon = "images/favicon.png";
+              palette = [
+                {
+                  scheme = "default";
+                  media = "(prefers-color-scheme: light)";
+                  primary = "black";
+                  accent = "blue";
+                  toggle = {
+                    icon = "material/brightness-7";
+                    name = "Switch to dark mode";
+                  };
+                }
+                {
+                  scheme = "slate";
+                  media = "(prefers-color-scheme: dark)";
+                  primary = "black";
+                  accent = "blue";
+                  toggle = {
+                    icon = "material/brightness-4";
+                    name = "Switch to light mode";
+                  };
+                }
+              ];
             };
+            plugins = ["search" "material-umami"];
             nav = [
               {"Introduction" = "index.md";}
               {"Usage" = "usage.md";}
               {"Examples" = "examples.md";}
               {"Reference" = "reference.md";}
-              {"Options" = "options.md";}
             ];
             markdown_extensions = [
               "pymdownx.superfences"
               "admonition"
             ];
+            extra.analytics = {
+              provider = "umami";
+              site_id = "d8354dfa-2ad2-4089-90d2-899b981aef22";
+              src = "https://analytics.tf/umami";
+              domains = "nixible.projects.tf";
+              feedback = {
+                title = "Was this page helpful?";
+                ratings = [
+                  {
+                    icon = "material/thumb-up-outline";
+                    name = "This page is helpful";
+                    data = "good";
+                    note = "Thanks for your feedback!";
+                  }
+                  {
+                    icon = "material/thumb-down-outline";
+                    name = "This page could be improved";
+                    data = "bad";
+                    note = "Thanks for your feedback! Please leave feedback by creating an issue :)";
+                  }
+                ];
+              };
+            };
           };
         };
         ci = {
@@ -142,34 +174,13 @@
         packages = let
           nblib = import ./lib {inherit pkgs lib;};
           ntlib = inputs.nixtest.lib {inherit pkgs lib;};
-          doclib = inputs.nix-mkdocs.lib {inherit lib pkgs;};
+        in {
-        in rec {
           tests = ntlib.mkNixtest {
             modules = ntlib.autodiscover {dir = ./tests;};
             args = {
               inherit pkgs nblib ntlib;
             };
           };
-          optionsDoc = doclib.mkOptionDocs {
-            module = {
-              imports = [
-                nblib.module
-                {
-                  _module.args.pkgs = pkgs;
-                }
-              ];
-            };
-            roots = [
-              {
-                url = "https://gitlab.com/TECHNOFAB/nixible/-/blob/main/lib";
-                path = toString ./lib;
-              }
-            ];
-          };
-          optionsDocs = pkgs.runCommand "options-docs" {} ''
-            mkdir -p $out
-            ln -s ${optionsDoc} $out/options.md
-          '';
         };
       };
     };

lib/module.nix

@@ -4,7 +4,7 @@
   config,
   ...
 }: let
-  inherit (lib) mkOptionType isType filterAttrs types mkOption literalExpression;
+  inherit (lib) mkOptionType isType filterAttrs types mkOption;
 
   unsetType = mkOptionType {
     name = "unset";
@@ -16,11 +16,7 @@
     _type = "unset";
   };
   isUnset = isType "unset";
-  unsetOr = typ:
+  unsetOr = types.either unsetType;
-    (types.either unsetType typ)
-    // {
-      description = typ.description;
-    };
 
   filterUnset = value:
     if builtins.isAttrs value && !builtins.hasAttr "_type" value
@@ -32,226 +28,93 @@
     then builtins.filter (elem: !isUnset elem) (map filterUnset value)
     else value;
 
-  mkUnsetOption = args:
-    mkOption args
-    // {
-      type = unsetOr args.type;
-      default = unset;
-      defaultText = literalExpression "unset";
-    };
-
   collectionType = types.submodule {
     options = {
       version = mkOption {
         type = types.str;
-        description = ''
+        description = "Version of collection";
-          Version of the collection.
-        '';
-        example = "1.0.0";
       };
       hash = mkOption {
         type = types.str;
-        description = ''
+        description = "Hash of the collection tarball";
-          SHA256 hash of the collection tarball for verification.
-        '';
-        example = "sha256-...";
       };
     };
   };
   tasksType = types.submodule {
     freeformType = types.attrsOf (types.attrsOf types.anything);
     options = {
-      name = mkUnsetOption {
+      name = mkOption {
-        type = types.str;
+        type = unsetOr types.str;
-        description = ''
+        default = unset;
-          Name of the task.
-        '';
       };
-      register = mkUnsetOption {
+      register = mkOption {
-        type = types.str;
+        type = unsetOr types.str;
-        description = ''
+        default = unset;
-          Register the task's output to a variable.
-        '';
       };
-      block = mkUnsetOption {
+      block = mkOption {
-        type = types.listOf tasksType;
+        type = unsetOr (types.listOf tasksType);
-        description = ''
+        default = unset;
-          A block of tasks to execute.
-        '';
       };
-      rescue = mkUnsetOption {
+      always = mkOption {
-        type = types.listOf tasksType;
+        type = unsetOr (types.listOf types.attrs);
-        description = ''
+        default = unset;
-          A list of tasks to execute on failure of block tasks.
-        '';
-      };
-      always = mkUnsetOption {
-        type = types.listOf types.attrs;
-        description = ''
-          Tasks that always run, regardless of task status.
-        '';
-      };
-      delegate_to = mkUnsetOption {
-        type = types.str;
-        description = ''
-          Delegate task execution to another host.
-        '';
-      };
-      ignore_errors = mkUnsetOption {
-        type = types.bool;
-        description = ''
-          Ignore errors and continue with the playbook.
-        '';
-      };
-      loop = mkUnsetOption {
-        type = types.anything;
-        description = ''
-          Define a loop for the task.
-        '';
-      };
-      when = mkUnsetOption {
-        type = types.str;
-        description = ''
-          Condition under which the task runs.
-        '';
       };
     };
   };
-  playType = types.submodule {
+  playbookType = types.listOf (types.submodule {
-    freeformType = types.attrsOf (types.attrsOf types.anything);
     options = {
       name = mkOption {
         type = types.str;
-        description = ''
+        description = "Name of the play";
-          Name of the play.
-        '';
       };
       hosts = mkOption {
         type = types.str;
-        description = ''
+        description = "The target hosts for this play (e.g., 'all', 'webservers')";
-          The target hosts for this play (e.g., 'all', 'webservers').
-        '';
-        example = "all";
       };
-      remote_user = mkUnsetOption {
+      become = mkOption {
-        type = types.str;
+        type = unsetOr types.bool;
-        description = ''
+        default = unset;
-          The user to execute tasks as on the remote server.
+        description = "Whether to use privilege escalation (become: yes)";
-        '';
       };
-      tags = mkUnsetOption {
+      gather_facts = mkOption {
-        type = types.listOf types.str;
+        type = unsetOr types.bool;
-        description = ''
+        default = unset;
-          Tags to filter tasks to run.
+        description = "";
-        '';
-      };
-      become = mkUnsetOption {
-        type = types.bool;
-        description = ''
-          Whether to use privilege escalation (become: yes).
-        '';
-      };
-      become_method = mkUnsetOption {
-        type = types.str;
-        description = ''
-          Privilege escalation method.
-        '';
-      };
-      vars = mkUnsetOption {
-        type = types.attrs;
-        description = ''
-          Variables for the play.
-        '';
-      };
-      gather_facts = mkUnsetOption {
-        type = types.either types.bool types.str;
-        description = ''
-          Whether to run the setup module to gather facts before executing tasks.
-        '';
-      };
-      when = mkUnsetOption {
-        type = types.str;
-        description = ''
-          Condition under which the play runs.
-        '';
       };
       tasks = mkOption {
         type = types.listOf tasksType;
         default = [];
-        description = ''
+        description = "List of tasks to execute in this play";
-          List of tasks to execute in this play
-        '';
       };
     };
-  };
+  });
-  playbookType = types.listOf playType;
 in {
   options = {
     ansiblePackage = mkOption {
       type = types.package;
       default = pkgs.python3Packages.callPackage ./ansible-core.nix {};
-      description = ''
+      description = "Ansible package to use (default doesn't have any collections installed for size)";
-        The Ansible package to use. The default package is optimized for size, by not including the gazillion collections that pkgs.ansible and pkgs.ansible-core include.
-      '';
-      example = literalExpression "pkgs.ansible";
     };
     collections = mkOption {
       type = types.attrsOf collectionType;
       default = {};
-      description = ''
+      description = "Collections to fetch and install";
-        Ansible collections to fetch and install from Galaxy.
-      '';
-      example = {
-        "community-general" = {
-          version = "8.0.0";
-          hash = "sha256-...";
-        };
-      };
     };
     dependencies = mkOption {
       type = types.listOf types.package;
       default = [];
       description = "List of packages to include at runtime";
-      example = literalExpression "[pkgs.git pkgs.rsync]";
     };
     playbook = mkOption {
       type = playbookType;
       apply = res: filterUnset res;
       description = "The actual playbook, defined as a Nix data structure";
-      example = [
-        {
-          name = "Configure servers";
-          hosts = "webservers";
-          become = true;
-          tasks = [
-            {
-              name = "Install nginx";
-              package = {
-                name = "nginx";
-                state = "present";
-              };
-            }
-          ];
-        }
-      ];
     };
 
     inventory = mkOption {
       type = types.attrs;
       default = {};
-      description = ''
+      description = "Ansible inventory, will be converted to json and passed to ansible";
-        Ansible inventory, will be converted to JSON and passed to Ansible.
-      '';
-      example = {
-        webservers = {
-          hosts = {
-            web1 = {ansible_host = "192.168.1.10";};
-          };
-          vars = {
-            http_port = 80;
-          };
-        };
-      };
     };
 
     inventoryFile = mkOption {