diff --git a/docs/images/favicon.png b/docs/images/favicon.png new file mode 100644 index 0000000..4b380b1 Binary files /dev/null and b/docs/images/favicon.png differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000..79fa6b8 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg deleted file mode 100644 index efba622..0000000 --- a/docs/images/logo.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/docs/options.md b/docs/options.md deleted file mode 100644 index 4ca74a4..0000000 --- a/docs/options.md +++ /dev/null @@ -1,3 +0,0 @@ -# Options - -{% include 'options.md' %} diff --git a/docs/reference.md b/docs/reference.md index e9f7434..3ef3160 100644 --- a/docs/reference.md +++ b/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. diff --git a/docs/style.css b/docs/style.css deleted file mode 100644 index b2ae4ff..0000000 --- a/docs/style.css +++ /dev/null @@ -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; -} - diff --git a/flake.lock b/flake.lock index 7f0a07d..15209f4 100644 --- a/flake.lock +++ b/flake.lock @@ -230,11 +230,11 @@ "nix-mkdocs": { "locked": { "dir": "lib", - "lastModified": 1757055638, - "narHash": "sha256-KHYSkEreFe4meXzSdEbknC/HwaQSNClQkc8vzHlAsMM=", + "lastModified": 1745841841, + "narHash": "sha256-297zPQbUlc7ZAYDoaD6mCmQxCC3Tr4YOKekRF1ArZ7g=", "owner": "technofab", "repo": "nixmkdocs", - "rev": "7840a5febdbeaf2da90babf6c94b3d0929d2bf74", + "rev": "c7e3c3b13ded25818e9789938387bba6f2cde690", "type": "gitlab" }, "original": { diff --git a/flake.nix b/flake.nix index dc9e417..7e10acf 100644 --- a/flake.nix +++ b/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 = { - enable = true; - 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; - }; + deps = pp: [ + pp.mkdocs-material + (pp.callPackage inputs.mkdocs-material-umami {}) + ]; 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"; - favicon = "images/logo.svg"; + logo = "images/logo.png"; + 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 rec { + in { 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 - ''; }; }; }; diff --git a/lib/module.nix b/lib/module.nix index bcbe713..b113ffb 100644 --- a/lib/module.nix +++ b/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: - (types.either unsetType typ) - // { - description = typ.description; - }; + unsetOr = types.either unsetType; 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 = '' - Version of the collection. - ''; - example = "1.0.0"; + description = "Version of collection"; }; hash = mkOption { type = types.str; - description = '' - SHA256 hash of the collection tarball for verification. - ''; - example = "sha256-..."; + description = "Hash of the collection tarball"; }; }; }; tasksType = types.submodule { freeformType = types.attrsOf (types.attrsOf types.anything); options = { - name = mkUnsetOption { - type = types.str; - description = '' - Name of the task. - ''; + name = mkOption { + type = unsetOr types.str; + default = unset; }; - register = mkUnsetOption { - type = types.str; - description = '' - Register the task's output to a variable. - ''; + register = mkOption { + type = unsetOr types.str; + default = unset; }; - block = mkUnsetOption { - type = types.listOf tasksType; - description = '' - A block of tasks to execute. - ''; + block = mkOption { + type = unsetOr (types.listOf tasksType); + default = unset; }; - rescue = mkUnsetOption { - type = types.listOf tasksType; - 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. - ''; + always = mkOption { + type = unsetOr (types.listOf types.attrs); + default = unset; }; }; }; - playType = types.submodule { - freeformType = types.attrsOf (types.attrsOf types.anything); + playbookType = types.listOf (types.submodule { 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'). - ''; - example = "all"; + description = "The target hosts for this play (e.g., 'all', 'webservers')"; }; - remote_user = mkUnsetOption { - type = types.str; - description = '' - The user to execute tasks as on the remote server. - ''; + become = mkOption { + type = unsetOr types.bool; + default = unset; + description = "Whether to use privilege escalation (become: yes)"; }; - tags = mkUnsetOption { - type = types.listOf types.str; - 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. - ''; + gather_facts = mkOption { + type = unsetOr types.bool; + default = unset; + description = ""; }; 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 = '' - 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"; + description = "Ansible package to use (default doesn't have any collections installed for size)"; }; collections = mkOption { type = types.attrsOf collectionType; default = {}; - description = '' - Ansible collections to fetch and install from Galaxy. - ''; - example = { - "community-general" = { - version = "8.0.0"; - hash = "sha256-..."; - }; - }; + description = "Collections to fetch and install"; }; 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. - ''; - example = { - webservers = { - hosts = { - web1 = {ansible_host = "192.168.1.10";}; - }; - vars = { - http_port = 80; - }; - }; - }; + description = "Ansible inventory, will be converted to json and passed to ansible"; }; inventoryFile = mkOption {