diff --git a/docs/images/favicon.png b/docs/images/favicon.png deleted file mode 100644 index 4b380b1..0000000 Binary files a/docs/images/favicon.png and /dev/null differ diff --git a/docs/images/logo.png b/docs/images/logo.png deleted file mode 100644 index 79fa6b8..0000000 Binary files a/docs/images/logo.png and /dev/null differ diff --git a/docs/images/logo.svg b/docs/images/logo.svg new file mode 100644 index 0000000..efba622 --- /dev/null +++ b/docs/images/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/options.md b/docs/options.md new file mode 100644 index 0000000..4ca74a4 --- /dev/null +++ b/docs/options.md @@ -0,0 +1,3 @@ +# Options + +{% include 'options.md' %} diff --git a/docs/reference.md b/docs/reference.md index 3ef3160..e9f7434 100644 --- a/docs/reference.md +++ b/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` - -**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. +See [options](./options.md) for more. diff --git a/docs/style.css b/docs/style.css new file mode 100644 index 0000000..b2ae4ff --- /dev/null +++ b/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; +} + diff --git a/flake.lock b/flake.lock index 15209f4..7f0a07d 100644 --- a/flake.lock +++ b/flake.lock @@ -230,11 +230,11 @@ "nix-mkdocs": { "locked": { "dir": "lib", - "lastModified": 1745841841, - "narHash": "sha256-297zPQbUlc7ZAYDoaD6mCmQxCC3Tr4YOKekRF1ArZ7g=", + "lastModified": 1757055638, + "narHash": "sha256-KHYSkEreFe4meXzSdEbknC/HwaQSNClQkc8vzHlAsMM=", "owner": "technofab", "repo": "nixmkdocs", - "rev": "c7e3c3b13ded25818e9789938387bba6f2cde690", + "rev": "7840a5febdbeaf2da90babf6c94b3d0929d2bf74", "type": "gitlab" }, "original": { diff --git a/flake.nix b/flake.nix index 7e10acf..dc9e417 100644 --- a/flake.nix +++ b/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: [ - pp.mkdocs-material - (pp.callPackage inputs.mkdocs-material-umami {}) - ]; + 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; + }; 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"; - 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"; - }; - } - ]; + logo = "images/logo.svg"; + favicon = "images/logo.svg"; }; - 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 + ''; }; }; }; diff --git a/lib/module.nix b/lib/module.nix index b113ffb..bcbe713 100644 --- a/lib/module.nix +++ b/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 { - type = unsetOr types.str; - default = unset; + name = mkUnsetOption { + type = types.str; + description = '' + Name of the task. + ''; }; - register = mkOption { - type = unsetOr types.str; - default = unset; + register = mkUnsetOption { + type = types.str; + description = '' + Register the task's output to a variable. + ''; }; - block = mkOption { - type = unsetOr (types.listOf tasksType); - default = unset; + block = mkUnsetOption { + type = types.listOf tasksType; + description = '' + A block of tasks to execute. + ''; }; - always = mkOption { - type = unsetOr (types.listOf types.attrs); - 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. + ''; }; }; }; - 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 { - type = unsetOr types.bool; - default = unset; - description = "Whether to use privilege escalation (become: yes)"; + remote_user = mkUnsetOption { + type = types.str; + description = '' + The user to execute tasks as on the remote server. + ''; }; - gather_facts = mkOption { - type = unsetOr types.bool; - default = unset; - description = ""; + 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. + ''; }; 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 {