From 731de62876e43d3d66c810c8a036f9f2eb376889 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Fri, 27 Jun 2025 09:54:23 +0200 Subject: [PATCH] docs: rename all references from 'buildClan' to 'lib.clan' --- clanServices/hello-world/tests/eval-tests.nix | 2 +- clanServices/wifi/tests/eval-tests.nix | 2 +- docs/mkdocs.yml | 2 +- docs/nix/flake-module.nix | 1 - docs/nix/render_options/__init__.py | 64 ++++++++----------- .../guides/authoring/clanModules/index.md | 4 +- docs/site/guides/flake-parts.md | 4 +- .../guides/getting-started/add-machines.md | 6 +- docs/site/guides/getting-started/deploy.md | 4 +- docs/site/guides/getting-started/secrets.md | 2 +- docs/site/guides/inventory.md | 6 +- docs/site/guides/macos.md | 4 +- .../site/guides/migrations/migration-guide.md | 4 +- docs/site/guides/more-machines.md | 14 ++-- docs/site/reference/index.md | 2 +- lib/modules/inventoryClass/interface.nix | 4 +- .../inventoryClass/roles-interface.nix | 2 +- 17 files changed, 54 insertions(+), 73 deletions(-) diff --git a/clanServices/hello-world/tests/eval-tests.nix b/clanServices/hello-world/tests/eval-tests.nix index 72b244354..7dfea9243 100644 --- a/clanServices/hello-world/tests/eval-tests.nix +++ b/clanServices/hello-world/tests/eval-tests.nix @@ -6,7 +6,7 @@ let testFlake = clanLib.buildClan { # Point to the folder of the module - # TODO: make this optional in buildClan + # TODO: make this optional directory = ./..; # Create some test machines diff --git a/clanServices/wifi/tests/eval-tests.nix b/clanServices/wifi/tests/eval-tests.nix index 9a53340d7..59d1efc36 100644 --- a/clanServices/wifi/tests/eval-tests.nix +++ b/clanServices/wifi/tests/eval-tests.nix @@ -6,7 +6,7 @@ let testFlake = clanLib.buildClan { # Point to the folder of the module - # TODO: make this optional in buildClan + # TODO: make this optional directory = ./..; # Create some test machines diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 761fb575a..ddf1d0810 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -168,7 +168,7 @@ nav: - reference/clan.core/state.md - reference/clan.core/vars.md - Nix API: - - buildClan: reference/nix-api/buildclan.md + - clan: reference/nix-api/clan.md - Inventory: reference/nix-api/inventory.md - Glossary: reference/glossary.md - Decisions: diff --git a/docs/nix/flake-module.nix b/docs/nix/flake-module.nix index 37fe01565..3624bbd5c 100644 --- a/docs/nix/flake-module.nix +++ b/docs/nix/flake-module.nix @@ -97,7 +97,6 @@ # Frontmatter format for clanModules export CLAN_MODULES_FRONTMATTER_DOCS=${clanModulesFrontmatter}/share/doc/nixos/options.json - # buildClan options export BUILD_CLAN_PATH=${buildClanOptions}/share/doc/nixos/options.json mkdir $out diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index ae80b0635..fd8bf49dd 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -383,36 +383,16 @@ For more information, see the [inventory guide](../../guides/inventory.md). `clan.admin.allowedkeys` - This means there are two equivalent ways to set the `allowedkeys` option. - Either via a nixos module or via the inventory interface. - **But it is recommended to keep together `imports` and `config` to preserve - locality of the module configuration.** - - === "Inventory" - - ```nix - clan-core.lib.buildClan { - inventory.services = { - admin.me = { - roles.default.machines = [ "jon" ]; - config.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ]; - }; + ```nix + clan-core.lib.clan { + inventory.services = { + admin.me = { + roles.default.machines = [ "jon" ]; + config.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ]; }; }; - ``` - - === "NixOS" - - ```nix - clan-core.lib.buildClan { - machines = { - jon = { - clan.admin.allowedkeys = [ "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQD..." ]; - imports = [ clanModules.admin ]; - }; - }; - }; - ``` + }; + ``` """ ) return "" @@ -708,18 +688,18 @@ def produce_build_clan_docs() -> None: msg = f"Environment variables are not set correctly: $out={OUT}" raise ClanError(msg) - output = """# BuildClan + output = """# Clan This provides an overview of the available arguments of the `clan` interface. Each attribute is documented below -- **buildClan**: A function that takes an attribute set.`. +- **clan-core.lib.clan**: A function that takes an attribute set. - ??? example "buildClan Example" + ??? example "clan Example" ```nix - buildClan { + clan { self = self; machines = { jon = { }; @@ -728,7 +708,13 @@ Each attribute is documented below }; ``` -- **flake-parts**: Each attribute can be defined via `clan.`. See our [flake-parts](../../guides/flake-parts.md) guide. +- **clan with flake-parts**: Import the FlakeModule + + After importing the FlakeModule you can define your `clan` as a flake attribute + + All attribute can be defined via `clan.*` + + Further information see: [flake-parts](../../guides/flake-parts.md) guide. ??? example "flake-parts Example" @@ -767,7 +753,7 @@ Each attribute is documented below for option in root.suboptions: output += options_docs_from_tree(option, init_level=2) - outfile = Path(OUT) / "nix-api/buildclan.md" + outfile = Path(OUT) / "nix-api/clan.md" outfile.parent.mkdir(parents=True, exist_ok=True) with Path.open(outfile, "w") as of: of.write(output) @@ -821,8 +807,8 @@ Typically needed by module authors to define roles, behavior and metadata for di See: [clanService Authoring Guide](../../guides/authoring/clanServices/index.md) """ - # Inventory options are already included under the buildClan attribute - # We just omitted them in the buildClan docs, because we want a separate output for the inventory model + # Inventory options are already included under the clan attribute + # We just omitted them in the clan docs, because we want a separate output for the inventory model with Path(CLAN_SERVICE_INTERFACE).open() as f: options: dict[str, dict[str, Any]] = json.load(f) @@ -860,11 +846,11 @@ def produce_inventory_docs() -> None: output = """# Inventory This provides an overview of the available attributes of the `inventory` model. -It can be set via the `inventory` attribute of the [`buildClan`](./buildclan.md#inventory) function, or via the [`clan.inventory`](./buildclan.md#inventory) attribute of flake-parts. +It can be set via the `inventory` attribute of the [`clan`](./clan.md#inventory) function, or via the [`clan.inventory`](./clan.md#inventory) attribute of flake-parts. """ - # Inventory options are already included under the buildClan attribute - # We just omitted them in the buildClan docs, because we want a separate output for the inventory model + # Inventory options are already included under the clan attribute + # We just omitted them in the clan docs, because we want a separate output for the inventory model with Path(BUILD_CLAN_PATH).open() as f: options: dict[str, dict[str, Any]] = json.load(f) diff --git a/docs/site/guides/authoring/clanModules/index.md b/docs/site/guides/authoring/clanModules/index.md index 2b8e4898e..2ee9d0951 100644 --- a/docs/site/guides/authoring/clanModules/index.md +++ b/docs/site/guides/authoring/clanModules/index.md @@ -52,7 +52,7 @@ clanModules/borgbackup ```nix title="flake.nix" # ... - buildClan { + clan-core.lib.clan { # 1. Add the module to the available clanModules with inventory support inventory.modules = { custom-module = ./modules/my_module; @@ -175,7 +175,7 @@ The following shows how to add options to your module. Configuration can be set as follows. ```nix title="flake.nix" - buildClan { + clan-core.lib.clan { inventory.services = { custom-module.instance_1 = { roles.default.machines = [ "machineA" ]; diff --git a/docs/site/guides/flake-parts.md b/docs/site/guides/flake-parts.md index a8a7343b1..c95db284b 100644 --- a/docs/site/guides/flake-parts.md +++ b/docs/site/guides/flake-parts.md @@ -27,7 +27,7 @@ inputs = { ## 2. Import the Clan flake-parts Module -After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../reference/nix-api/buildclan.md) available within `mkFlake`. +After updating your flake inputs, the next step is to import the Clan flake-parts module. This will make the [Clan options](../reference/nix-api/clan.md) available within `mkFlake`. ```nix { @@ -62,7 +62,7 @@ Next you'll need to configure Clan wide settings and define machines, here's an ]; # Define your Clan - # See: https://docs.clan.lol/reference/nix-api/buildclan/ + # See: https://docs.clan.lol/reference/nix-api/clan/ clan = { # Clan wide settings meta.name = ""; # This is required and must be unique diff --git a/docs/site/guides/getting-started/add-machines.md b/docs/site/guides/getting-started/add-machines.md index 2d46f3f60..6e3022285 100644 --- a/docs/site/guides/getting-started/add-machines.md +++ b/docs/site/guides/getting-started/add-machines.md @@ -8,7 +8,7 @@ Clan currently offers the following methods to configure machines: !!! Success "Recommended for advanced Nix users" - - flake.nix (i.e. via `buildClan`) + - flake.nix (i.e. via `clan-core.lib.clan`) - `machine` argument - `inventory` argument @@ -30,7 +30,7 @@ In the `flake.nix` file: === "**normal flake template**" ```nix title="flake.nix" hl_lines="3" - buildClan { + clan-core.lib.clan { # Set a unique name meta.name = "Lobsters"; # Necessary for importing external Clan services @@ -60,7 +60,7 @@ Adding or configuring a new machine requires two simple steps: ???+ Note "Cloud Machines" NixOS can cause strange issues when booting in certain cloud environments. - + - If on Linode: Make sure that the system uses Direct Disk boot kernel (found in the configuration pannel) ### Step 1. Identify Target Disk-ID diff --git a/docs/site/guides/getting-started/deploy.md b/docs/site/guides/getting-started/deploy.md index 8d1f1adcd..7cd4df0bf 100644 --- a/docs/site/guides/getting-started/deploy.md +++ b/docs/site/guides/getting-started/deploy.md @@ -175,7 +175,7 @@ During an update, the CLI will SSH into the build host and run `nixos-rebuild` f ```{.nix hl_lines="5" .no-copy} -buildClan { +clan { # ... machines = { "jon" = { @@ -191,7 +191,7 @@ To exclude machines from being updated when running `clan machines update` witho one can set the `clan.deployment.requireExplicitUpdate` option to true: ```{.nix hl_lines="5" .no-copy} -buildClan { +clan { # ... machines = { "jon" = { diff --git a/docs/site/guides/getting-started/secrets.md b/docs/site/guides/getting-started/secrets.md index 5d13559b0..e6792f22c 100644 --- a/docs/site/guides/getting-started/secrets.md +++ b/docs/site/guides/getting-started/secrets.md @@ -82,7 +82,7 @@ are loaded when using Clan: outputs = { self, clan-core, ... }: let - clan = clan-core.clanLib.buildClan { + clan = clan-core.clanLib.clan { inherit self; meta.name = "myclan"; diff --git a/docs/site/guides/inventory.md b/docs/site/guides/inventory.md index 7de9bb190..d829812ee 100644 --- a/docs/site/guides/inventory.md +++ b/docs/site/guides/inventory.md @@ -47,7 +47,7 @@ Each service can still be customized and configured according to the modules opt See also: [Multiple Service Instances](#multiple-service-instances) ```{.nix hl_lines="6-7"} - buildClan { + clan-core.lib.clan { inventory = { services = { borgbackup.instance_1 = { @@ -69,7 +69,7 @@ It is possible to add services to multiple machines via tags as shown !!! Example "Tags Example" ```{.nix hl_lines="5 8 14"} - buildClan { + clan-core.lib.clan { inventory = { machines = { "jon" = { @@ -101,7 +101,7 @@ It is possible to add services to multiple machines via tags as shown In this example `backup_server` has role `client` and `server` in different instances. ```{.nix hl_lines="11 14"} - buildClan { + clan-core.lib.clan { inventory = { machines = { "jon" = {}; diff --git a/docs/site/guides/macos.md b/docs/site/guides/macos.md index ec9c607a5..6ef9ee1a3 100644 --- a/docs/site/guides/macos.md +++ b/docs/site/guides/macos.md @@ -13,10 +13,10 @@ Currently, Clan supports the following features for macOS: In this example, we'll name the machine `yourmachine`. Replace this with your preferred machine name. -=== "**If using core.lib.buildClan**" +=== "**If using clan-core.lib.clan**" ```nix -buildClan { +clan-core.lib.clan { inventory = { machines.yourmachine.machineClass = "darwin"; }; diff --git a/docs/site/guides/migrations/migration-guide.md b/docs/site/guides/migrations/migration-guide.md index b74eef7db..59404f9de 100644 --- a/docs/site/guides/migrations/migration-guide.md +++ b/docs/site/guides/migrations/migration-guide.md @@ -68,7 +68,7 @@ output parameters. The existing `nixosConfigurations` output of your flake will be created by clan. In addition, a new `clanInternals` output will be added. Since both of -these are provided by the output of `lib.buildClan`, a common syntax is to use a +these are provided by the output of `clan-core.lib.clan`, a common syntax is to use a `let...in` statement to create your clan and access it's parameters in the flake outputs. @@ -85,7 +85,7 @@ For the provide flake example, your flake should now look like this: outputs = { self, nixpkgs, clan-core, ... }: let - clan = clan-core.lib.buildClan { + clan = clan-core.lib.clan { self = self; # this needs to point at the repository root specialArgs = {}; meta.name = throw "Change me to something unique"; diff --git a/docs/site/guides/more-machines.md b/docs/site/guides/more-machines.md index 4cf7054cd..5ce064626 100644 --- a/docs/site/guides/more-machines.md +++ b/docs/site/guides/more-machines.md @@ -17,19 +17,14 @@ Every folder `machines/{machineName}` will be registered automatically as a Clan - [x] `machines/{machineName}/facter.json` Automatically configured, for further information see [nixos-facter](https://clan.lol/blog/nixos-facter/) - [x] `machines/{machineName}/disko.nix` Automatically loaded, for further information see the [disko docs](https://github.com/nix-community/disko/blob/master/docs/quickstart.md). - - ## Manual declaration -Machines can also be added manually under `buildClan`, `clan.*` in flake-parts or via [`inventory`](../guides/inventory.md). - -!!! Note - It is possible to use `inventory` and `buildClan` together at the same time. +Machines can be added via [`clan.inventory.machines`](../guides/inventory.md) or in `clan.machines`, which allows for defining NixOS options. === "**Individual Machine Configuration**" ```{.nix} - buildClan { + clan-core.lib.clan { machines = { "jon" = { # Any valid nixos config @@ -41,12 +36,13 @@ Machines can also be added manually under `buildClan`, `clan.*` in flake-parts o === "**Inventory Configuration**" ```{.nix} - buildClan { + clan-core.lib.clan { inventory = { machines = { "jon" = { - # Inventory machines can set tags + # Inventory can set tags and other metadata tags = [ "zone1" ]; + deploy.targetHost = "root@jon"; }; }; }; diff --git a/docs/site/reference/index.md b/docs/site/reference/index.md index 511ffda9f..bb08355a8 100644 --- a/docs/site/reference/index.md +++ b/docs/site/reference/index.md @@ -7,7 +7,7 @@ This section of the site provides an overview of available options and commands - Learn how to use the [Clan CLI](./cli/index.md) - Explore available services and application [modules](./clanModules/index.md) - Discover [configuration options](./clan.core/index.md) that manage essential features -- Find descriptions of the [Nix interfaces](./nix-api/buildclan.md) for defining a Clan +- Find descriptions of the [Nix interfaces](./nix-api/clan.md) for defining a Clan --- diff --git a/lib/modules/inventoryClass/interface.nix b/lib/modules/inventoryClass/interface.nix index 6807cdca6..4495c7cbf 100644 --- a/lib/modules/inventoryClass/interface.nix +++ b/lib/modules/inventoryClass/interface.nix @@ -55,7 +55,7 @@ let Supported types: - - **Strings**: Interpreted relative to the 'directory' passed to buildClan. + - **Strings**: Interpreted relative to the 'directory' passed to `lib.clan`. - **Paths**: should be relative to the current file. - **Any**: Nix expression must be serializable to JSON. @@ -146,7 +146,7 @@ in ???+ example ```nix - buildClan { + clan-core.lib.clan { # 1. Add the module to the available inventory modules inventory.modules = { custom-module = ./modules/my_module; diff --git a/lib/modules/inventoryClass/roles-interface.nix b/lib/modules/inventoryClass/roles-interface.nix index da66774d9..562e7079f 100644 --- a/lib/modules/inventoryClass/roles-interface.nix +++ b/lib/modules/inventoryClass/roles-interface.nix @@ -44,7 +44,7 @@ in Supported types: - - **Strings**: Interpreted relative to the 'directory' passed to buildClan. + - **Strings**: Interpreted relative to the 'directory' passed to `lib.clan`. - **Paths**: should be relative to the current file. - **Any**: Nix expression must be serializable to JSON.