docs: move service definition into explizit markdown file

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

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)
 

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.

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`:

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
 

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:
 

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
 

docs/site/index.md

@@ -128,7 +128,7 @@ hide:
 
     Search all options
 
--   [Services](./services/official/index.md)
+-   [Services](./services/definition.md)
 
     ---
 

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).