From 76d1d9b1678c26a70d276ee48e54884844904e3b Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Fri, 3 Oct 2025 18:17:13 +0200 Subject: [PATCH] docs: consistent options reference --- docs/mkdocs.yml | 7 ++++--- docs/nix/render_options/__init__.py | 10 ++++++++-- docs/site/guides/services/community.md | 6 +++--- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a0308e8d0..fd06e1290 100644 --- a/docs/mkdocs.yml +++ b/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 diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index af622711f..9424246fa 100644 --- a/docs/nix/render_options/__init__.py +++ b/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) diff --git a/docs/site/guides/services/community.md b/docs/site/guides/services/community.md index 56bda9e14..c34443b8d 100644 --- a/docs/site/guides/services/community.md +++ b/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)