docs: update nixmkdocs, use svg logo, add style.css, set site_url

docs/images/logo.svg

@@ -0,0 +1 @@
+<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

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

docs/reference.md

@@ -84,132 +84,6 @@ mkNixibleCli config
 Creates a CLI executable for your Nixible configuration.
 Basically `(mkNixible config).config.cli`.
 
-## Configuration Options
+______________________________________________________________________
 
-### `ansiblePackage`
+See [options](./options.md) for more.
-
-**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

@@ -0,0 +1,15 @@
+.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": 1745841841,
+        "lastModified": 1757055638,
-        "narHash": "sha256-297zPQbUlc7ZAYDoaD6mCmQxCC3Tr4YOKekRF1ArZ7g=",
+        "narHash": "sha256-KHYSkEreFe4meXzSdEbknC/HwaQSNClQkc8vzHlAsMM=",
         "owner": "technofab",
         "repo": "nixmkdocs",
-        "rev": "c7e3c3b13ded25818e9789938387bba6f2cde690",
+        "rev": "7840a5febdbeaf2da90babf6c94b3d0929d2bf74",
         "type": "gitlab"
       },
       "original": {

flake.nix

@@ -17,6 +17,7 @@
       perSystem = {
         lib,
         pkgs,
+        self',
         config,
         ...
       }: {
@@ -38,80 +39,47 @@
             convco.enable = true;
           };
         };
-        doc = {
+        docs."default".config = {
           path = ./docs;
-          deps = pp: [
+          material = {
-            pp.mkdocs-material
+            enable = true;
-            (pp.callPackage inputs.mkdocs-material-umami {})
+            colors = {
-          ];
+              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";
-            edit_uri = "edit/main/docs/";
+            extra_css = ["style.css"];
             theme = {
-              name = "material";
-              features = ["content.code.copy" "content.action.edit"];
               icon.repo = "simple/gitlab";
-              logo = "images/logo.png";
+              logo = "images/logo.svg";
-              favicon = "images/favicon.png";
+              favicon = "images/logo.svg";
-              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 = {
@@ -174,13 +142,34 @@
         packages = let
           nblib = import ./lib {inherit pkgs lib;};
           ntlib = inputs.nixtest.lib {inherit pkgs lib;};
-        in {
+          doclib = inputs.nix-mkdocs.lib {inherit lib pkgs;};
+        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;
+  inherit (lib) mkOptionType isType filterAttrs types mkOption literalExpression;
 
   unsetType = mkOptionType {
     name = "unset";
@@ -16,7 +16,11 @@
     _type = "unset";
   };
   isUnset = isType "unset";
-  unsetOr = types.either unsetType;
+  unsetOr = typ:
+    (types.either unsetType typ)
+    // {
+      description = typ.description;
+    };
 
   filterUnset = value:
     if builtins.isAttrs value && !builtins.hasAttr "_type" value
@@ -28,93 +32,226 @@
     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 = "Version of collection";
+        description = ''
+          Version of the collection.
+        '';
+        example = "1.0.0";
       };
       hash = mkOption {
         type = types.str;
-        description = "Hash of the collection tarball";
+        description = ''
+          SHA256 hash of the collection tarball for verification.
+        '';
+        example = "sha256-...";
       };
     };
   };
   tasksType = types.submodule {
     freeformType = types.attrsOf (types.attrsOf types.anything);
     options = {
-      name = mkOption {
+      name = mkUnsetOption {
-        type = unsetOr types.str;
+        type = types.str;
-        default = unset;
+        description = ''
+          Name of the task.
+        '';
       };
-      register = mkOption {
+      register = mkUnsetOption {
-        type = unsetOr types.str;
+        type = types.str;
-        default = unset;
+        description = ''
+          Register the task's output to a variable.
+        '';
       };
-      block = mkOption {
+      block = mkUnsetOption {
-        type = unsetOr (types.listOf tasksType);
+        type = types.listOf tasksType;
-        default = unset;
+        description = ''
+          A block of tasks to execute.
+        '';
       };
-      always = mkOption {
+      rescue = mkUnsetOption {
-        type = unsetOr (types.listOf types.attrs);
+        type = types.listOf tasksType;
-        default = unset;
+        description = ''
+          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.
+        '';
       };
     };
   };
-  playbookType = types.listOf (types.submodule {
+  playType = types.submodule {
+    freeformType = types.attrsOf (types.attrsOf types.anything);
     options = {
       name = mkOption {
         type = types.str;
-        description = "Name of the play";
+        description = ''
+          Name of the play.
+        '';
       };
       hosts = mkOption {
         type = types.str;
-        description = "The target hosts for this play (e.g., 'all', 'webservers')";
+        description = ''
+          The target hosts for this play (e.g., 'all', 'webservers').
+        '';
+        example = "all";
       };
-      become = mkOption {
+      remote_user = mkUnsetOption {
-        type = unsetOr types.bool;
+        type = types.str;
-        default = unset;
+        description = ''
-        description = "Whether to use privilege escalation (become: yes)";
+          The user to execute tasks as on the remote server.
+        '';
       };
-      gather_facts = mkOption {
+      tags = mkUnsetOption {
-        type = unsetOr types.bool;
+        type = types.listOf types.str;
-        default = unset;
+        description = ''
-        description = "";
+          Tags to filter tasks to run.
+        '';
+      };
+      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 = "List of tasks to execute in this play";
+        description = ''
+          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 = "Ansible package to use (default doesn't have any collections installed for size)";
+      description = ''
+        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 = "Collections to fetch and install";
+      description = ''
+        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 = "Ansible inventory, will be converted to json and passed to ansible";
+      description = ''
+        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 {