Merge pull request 'docs: move services into its reserved category' (#5372) from docs-simplify into main

Reviewed-on: https://git.clan.lol/clan/clan-core/pulls/5372

docs/mkdocs.yml

@@ -63,8 +63,8 @@ nav:
       - Inventory:
           - Introduction to Inventory: guides/inventory/inventory.md
           - File Autoincludes: guides/inventory/autoincludes.md
-      - Clan Services:
-          - Inventory Guide: guides/inventory/clanServices.md
+      - Services:
+          - Introduction to Services: guides/services/introduction-to-services.md
           - Author Your Own Service: guides/services/community.md
       - Vars:
           - Introduction to Vars: guides/vars/vars-overview.md
@@ -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

@@ -8,7 +8,7 @@ In Clan Services are multi-Host & role-based:
 
 - You can use tags instead of explicit machine names.
 
-To learn more: [Guide about clanService](../guides/inventory/clanServices.md)
+To learn more: [Guide about clanService](../guides/services/introduction-to-services.md)
 
 !!! Important
     It is recommended to add at least one networking service such as `zerotier` that allows to reach all your clan machines from your setup computer across the globe.
@@ -38,8 +38,8 @@ To learn more: [Guide about clanService](../guides/inventory/clanServices.md)
 }
 ```
 
-1. See [reference/clanServices](../services/official/index.md) for all available services and how to configure them.
-   Or read [authoring/clanServices](../guides/services/community.md) if you want to bring your own
+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:
 
@@ -380,4 +380,4 @@ instances = {
 
 * [Inventory Concept](../../guides/inventory/inventory.md)
 * [Authoring a 'clan.service' module](../../guides/services/community.md)
-* [ClanServices](../../guides/inventory/clanServices.md)
+* [ClanServices](../../guides/services/introduction-to-services.md)

docs/site/guides/services/introduction-to-services.md

@@ -1,11 +1,11 @@
-Clan's inventory system is a composable way to define and deploy services across
+Clan's services are a modular way to define and deploy services across
 machines.
 
-This guide shows how to **instantiate** a `clanService`, explains how service
-definitions are structured in your inventory, and how to pick or create services
+This guide shows how to **instantiate** a **service**, explains how service
+definitions are structured and how to pick or create services
 from modules exposed by flakes.
 
-The term **Multi-host-modules** was introduced previously in the [nixus
+A similar term: **Multi-host-modules** was introduced previously in the [nixus
 repository](https://github.com/infinisil/nixus) and represents a similar
 concept.
 
@@ -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

@@ -74,11 +74,11 @@ hide:
   <input type="checkbox" id="clan-readmore" class="clamp-toggle" />
   <div class="clamp-content">
     <p><a href="https://clan.lol/">Clan</a> is a peer-to-peer computer management framework that empowers you to selfhost in a reliable and scalable way</strong>.</p>
-    <p>Built on NixOS, Clan provides a declarative interface for managing machines</strong> with <a href="/guides/vars/vars-overview/">Resource management</a>, <a href="guides/networking/networking/">Networking</a>, and <a href="
+    <p>Built on NixOS, Clan provides a declarative interface for managing machines</strong> with <a href="/guides/vars/vars-overview/">Resource management</a>, <a href="/guides/networking/networking/">Networking</a>, and <a href="
     /guides/backups/backup-intro/">Backups</a>.</p>
     <p>Whether you're running a homelab or maintaining critical computing infrastructure, Clan will help reduce maintenance burden</strong> by allowing a git repository to define your whole network</strong> of computers.</p>
     <p>In combination with <a href="https://github.com/Mic92/sops-nix">sops-nix</a>, <a href="https://github.com/nix-community/nixos-anywhere">nixos-anywhere</a> and <a href="https://github.com/nix-community/disko">disko</a>, Clan makes it possible to have collaborative infrastructure</strong>.</p>
-    <p>At the heart of Clan are <a href="/reference/clanServices">Clan Services</a> - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, everyone can <a href="/guides/services/community/">create custom services</a> tailored to your specific needs.</p>
+    <p>At the heart of Clan are <a href="/services/official/">Clan Services</a> - the core concept that enables you to add functionality across multiple machines in your network. While Clan ships with essential core services, everyone can <a href="/guides/services/community/">create custom services</a> tailored to your specific needs.</p>
   </div>
   <label class="clamp-more" for="clan-readmore"></label>
 </div>
@@ -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).