docs: consistent options reference

docs/mkdocs.yml

@@ -105,8 +105,10 @@ nav:
 
   - Reference:
       - Overview: reference/index.md
-      - Clan Options: reference/options/clan.md
-      - Clan Inventory Options: reference/options/clan_inventory.md
+      - Options:
+          - reference/options/clan.md
+          - reference/options/clan_inventory.md
+          - reference/options/clan_service.md
 
       - clan.core (Machine Options):
           - Overview: reference/clan.core/index.md
@@ -137,7 +139,6 @@ nav:
           - reference/cli/vars.md
           - reference/cli/vms.md
 
-      - Clan Service API: reference/clan-service-author-interface.md
 
       - HTTP API: api.md
 

docs/nix/render_options/__init__.py

@@ -439,7 +439,7 @@ Typically needed by module authors to define roles, behavior and metadata for di
         # for option in options_tree.suboptions:
         output += options_docs_from_tree(options_tree, init_level=2)
 
-    outfile = Path(OUT) / "reference" / "clan-service-author-interface.md"
+    outfile = Path(OUT) / "reference/options" / "clan_service.md"
     outfile.parent.mkdir(parents=True, exist_ok=True)
     with Path.open(outfile, "w") as of:
         of.write(output)
@@ -454,7 +454,7 @@ def produce_inventory_docs() -> None:
         msg = f"Environment variables are not set correctly: $out={OUT}"
         raise ClanError(msg)
 
-    output = """# Inventory
+    output = """# Inventory Submodule
 This provides an overview of the available options of the `inventory` model.
 
 It can be set via the `inventory` attribute of the [`clan`](/reference/options/clan_inventory.md) function, or via the [`clan.inventory`](/reference/options/clan_inventory.md) attribute of flake-parts.
@@ -514,6 +514,12 @@ or via the [`clan`](/reference/options/clan.md) attribute of flake-parts.
         # Exclude inventory options
         for option in clan_root_option.suboptions:
             if "inventory" in option.name:
+                output += """## Inventory
+
+Attribute: `inventory`
+
+See: [Inventory Submodule](/reference/options/clan_inventory.md)
+"""
                 continue
             output += options_docs_from_tree(option, init_level=2)
 

docs/site/guides/services/community.md

@@ -5,7 +5,7 @@
 This section explains how to author a clan service module.
 We discussed the initial architecture in [01-clan-service-modules](/decisions/01-Clan-Modules.md) and decided to rework the format.
 
-For the full specification and current state see: **[Service Author Reference](/reference/clanServices/clan-service-author-interface.md)**
+For the full specification and current state see: **[Service Author Reference](/reference/options/clan_service.md)**
 
 ### A Minimal module
 
@@ -47,7 +47,7 @@ The imported module file must fulfill at least the following requirements:
 }
 ```
 
-For more attributes see: **[Service Author Reference](/reference/clanServices/clan-service-author-interface.md)**
+For more attributes see: **[Service Author Reference](/reference/options/clan_service.md)**
 
 ### Adding functionality to the module
 
@@ -300,6 +300,6 @@ instnaces.machine-type = {
 
 ## Further Reading
 
-- [Reference Documentation for Service Authors](/reference/clanServices/clan-service-author-interface.md)
+- [Reference Documentation for Service Authors](/reference/options/clan_service.md)
 - [Migration Guide from ClanModules to ClanServices](/guides/migrations/migrate-inventory-services.md)
 - [Decision that lead to ClanServices](/decisions/01-Clan-Modules.md)