diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 659f0f4ef..7e8649b15 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -151,7 +151,7 @@ nav: - decisions/template.md - Glossary: reference/glossary.md - Services: - - Introduction to ClanServices: services/official/index.md + - services/definition.md # Generated list from the list of official services - Official: - services/official/admin.md diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index f8361e136..faedf8fcd 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -309,32 +309,6 @@ def produce_clan_service_docs() -> None: msg = f"Environment variables are not set correctly: $out={OUT}" raise ClanError(msg) - indexfile = Path(OUT) / "services/official" / "index.md" - indexfile.parent.mkdir( - parents=True, - exist_ok=True, - ) - index = "# Clan Services\n\n" - index += """ -**`clanServices`** are modular building blocks that simplify the configuration and orchestration of multi-host services. - -Each `clanService`: - -* Is a module of class **`clan.service`** -* Can define **roles** (e.g., `client`, `server`) -* Uses **`inventory.instances`** to configure where and how it is deployed - -!!! Note - `clanServices` are part of Clan's next-generation service model and are intended to replace `clanModules`. - - See [Migration Guide](../../guides/migrations/migrate-inventory-services.md) for help on migrating. - -Learn how to use `clanServices` in practice in the [Using clanServices guide](../../guides/inventory/clanServices.md). -""" - - with indexfile.open("w") as of: - of.write(index) - with Path(CLAN_MODULES_VIA_SERVICE).open() as f3: service_links: dict[str, dict[str, dict[str, Any]]] = json.load(f3) diff --git a/docs/site/getting-started/add-services.md b/docs/site/getting-started/add-services.md index c702b9d31..66505944b 100644 --- a/docs/site/getting-started/add-services.md +++ b/docs/site/getting-started/add-services.md @@ -38,7 +38,7 @@ To learn more: [Guide about clanService](../guides/services/introduction-to-serv } ``` -1. See [services/official](../services/official/index.md) for all available services and how to configure them. +1. See [services/official](../services/definition.md) for all available services and how to configure them. Or read [guides/services](../guides/services/community.md) if you want to bring your own 2. Replace `__YOUR_CONTROLLER_` with the *name* of your machine. diff --git a/docs/site/getting-started/add-users.md b/docs/site/getting-started/add-users.md index aa55d81f9..271aaaa6a 100644 --- a/docs/site/getting-started/add-users.md +++ b/docs/site/getting-started/add-users.md @@ -10,7 +10,7 @@ Defining users can be done in many different ways. We want to highlight two appr To add a first *user* this guide will be leveraging two things: -- [services](../services/official/index.md): Allows to bind arbitrary logic to something we call an `ìnstance`. +- [services](../services/definition.md): Allows to bind arbitrary logic to something we call an `ìnstance`. - [services/users](../services/official/users.md): Implements logic for adding a single user perInstance. The example shows how to add a user called `jon`: diff --git a/docs/site/guides/inventory/inventory.md b/docs/site/guides/inventory/inventory.md index 363087ffe..351c4de33 100644 --- a/docs/site/guides/inventory/inventory.md +++ b/docs/site/guides/inventory/inventory.md @@ -23,7 +23,7 @@ The following tutorial will walk through setting up a Backup service where the t The inventory defines `instances` of clan services. Membership of `machines` is defined via `roles` exclusively. -See each [modules documentation](../../services/official/index.md) for its available roles. +See each [modules documentation](../../services/definition.md) for its available roles. ### Adding services to machines diff --git a/docs/site/guides/migrations/migrate-inventory-services.md b/docs/site/guides/migrations/migrate-inventory-services.md index 4880fb7a3..f4d348471 100644 --- a/docs/site/guides/migrations/migrate-inventory-services.md +++ b/docs/site/guides/migrations/migrate-inventory-services.md @@ -157,7 +157,7 @@ instances = { ### Move `services` entries to `instances` -Check if a service that you use has been migrated [In our reference](../../services/official/index.md) +Check if a service that you use has been migrated [In our reference](../../services/definition.md) In your inventory, move it from: diff --git a/docs/site/guides/services/introduction-to-services.md b/docs/site/guides/services/introduction-to-services.md index 9dfad2218..b1574c708 100644 --- a/docs/site/guides/services/introduction-to-services.md +++ b/docs/site/guides/services/introduction-to-services.md @@ -68,7 +68,7 @@ inventory.instances = { ## Module Settings Each role might expose configurable options. See clan's [clanServices -reference](../../services/official/index.md) for all available options. +reference](../../services/definition.md) for all available options. Settings can be set in per-machine or per-role. The latter is applied to all machines that are assigned to that role. @@ -155,7 +155,7 @@ inventory.instances = { You can use services exposed by Clan's core module library, `clan-core`. -🔗 See: [List of Available Services in clan-core](../../services/official/index.md) +🔗 See: [List of Available Services in clan-core](../../services/definition.md) ## Defining Your Own Service diff --git a/docs/site/index.md b/docs/site/index.md index f9aaa08b0..b964f169b 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -128,7 +128,7 @@ hide: Search all options -- [Services](./services/official/index.md) +- [Services](./services/definition.md) --- diff --git a/docs/site/services/definition.md b/docs/site/services/definition.md new file mode 100644 index 000000000..e9aeb1ce1 --- /dev/null +++ b/docs/site/services/definition.md @@ -0,0 +1,14 @@ +**`clanServices`** are modular building blocks that simplify the configuration and orchestration of multi-host services. + +Each `clanService`: + +* Is a module of class **`clan.service`** +* Can define **roles** (e.g., `client`, `server`) +* Uses **`inventory.instances`** to configure where and how it is deployed + +!!! Note + `clanServices` are part of Clan's next-generation service model and are intended to replace `clanModules`. + + See [Migration Guide](../guides/migrations/migrate-inventory-services.md) for help on migrating. + +Learn how to use `clanServices` in practice in the [Using clanServices guide](../guides/services/introduction-to-services.md).