From f9c8ed74e1244d4bbe22356ddd2e4735266ca7a3 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Fri, 3 Oct 2025 17:06:14 +0200 Subject: [PATCH] docs: decisions harmonize with file tree --- docs/mkdocs.yml | 14 +++++++------- docs/nix/render_options/__init__.py | 2 +- .../{01-ClanModules.md => 01-Clan-Modules.md} | 2 -- .../{02-clan-api.md => 02-clan-as-library.md} | 2 -- docs/site/decisions/03-adr-numbering-process.md | 2 -- docs/site/decisions/05-deployment-parameters.md | 2 -- .../{README.md => Architecture-decisions.md} | 6 ++---- docs/site/decisions/{_template.md => template.md} | 2 +- docs/site/guides/services/community.md | 12 ++++++------ 9 files changed, 17 insertions(+), 27 deletions(-) rename docs/site/decisions/{01-ClanModules.md => 01-Clan-Modules.md} (99%) rename docs/site/decisions/{02-clan-api.md => 02-clan-as-library.md} (99%) rename docs/site/decisions/{README.md => Architecture-decisions.md} (77%) rename docs/site/decisions/{_template.md => template.md} (93%) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b75bbf123..22f361890 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -142,13 +142,13 @@ nav: - HTTP API: api.md - Decisions: - - Architecture Decisions: decisions/README.md - - 01-clanModules: decisions/01-ClanModules.md - - 02-clan-api: decisions/02-clan-api.md - - 03-adr-numbering-process: decisions/03-adr-numbering-process.md - - 04-fetching-nix-from-python: decisions/04-fetching-nix-from-python.md - - 05-deployment-parameters: decisions/05-deployment-parameters.md - - Template: decisions/_template.md + - decisions/Architecture-decisions.md + - decisions/01-Clan-Modules.md + - decisions/02-clan-as-library.md + - decisions/03-adr-numbering-process.md + - decisions/04-fetching-nix-from-python.md + - decisions/05-deployment-parameters.md + - decisions/template.md - Glossary: reference/glossary.md - Services: - Introduction to ClanServices: reference/clanServices/index.md diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py index e3da219a1..c37e2d730 100644 --- a/docs/nix/render_options/__init__.py +++ b/docs/nix/render_options/__init__.py @@ -455,7 +455,7 @@ def produce_inventory_docs() -> None: output = """# Inventory This provides an overview of the available options of the `inventory` model. -It can be set via the `inventory` attribute of the [`clan`](./clan.md#inventory) function, or via the [`clan.inventory`](./clan.md#inventory) attribute of flake-parts. +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. """ # Inventory options are already included under the clan attribute diff --git a/docs/site/decisions/01-ClanModules.md b/docs/site/decisions/01-Clan-Modules.md similarity index 99% rename from docs/site/decisions/01-ClanModules.md rename to docs/site/decisions/01-Clan-Modules.md index 850a1f5fb..b0857efb0 100644 --- a/docs/site/decisions/01-ClanModules.md +++ b/docs/site/decisions/01-Clan-Modules.md @@ -1,5 +1,3 @@ -# Clan service modules - ## Status Accepted diff --git a/docs/site/decisions/02-clan-api.md b/docs/site/decisions/02-clan-as-library.md similarity index 99% rename from docs/site/decisions/02-clan-api.md rename to docs/site/decisions/02-clan-as-library.md index a51730e91..4ef7df292 100644 --- a/docs/site/decisions/02-clan-api.md +++ b/docs/site/decisions/02-clan-as-library.md @@ -1,5 +1,3 @@ -# Clan as library - ## Status Accepted diff --git a/docs/site/decisions/03-adr-numbering-process.md b/docs/site/decisions/03-adr-numbering-process.md index 11d18c844..0aec8d144 100644 --- a/docs/site/decisions/03-adr-numbering-process.md +++ b/docs/site/decisions/03-adr-numbering-process.md @@ -1,5 +1,3 @@ -# ADR Numbering process - ## Status Proposed after some conversation between @lassulus, @Mic92, & @lopter. diff --git a/docs/site/decisions/05-deployment-parameters.md b/docs/site/decisions/05-deployment-parameters.md index 23f438833..046b36c98 100644 --- a/docs/site/decisions/05-deployment-parameters.md +++ b/docs/site/decisions/05-deployment-parameters.md @@ -1,5 +1,3 @@ -# deployment parameters: evalHost, buildHost, targetHost - ## Status accepted diff --git a/docs/site/decisions/README.md b/docs/site/decisions/Architecture-decisions.md similarity index 77% rename from docs/site/decisions/README.md rename to docs/site/decisions/Architecture-decisions.md index e6839a4ac..607ceff43 100644 --- a/docs/site/decisions/README.md +++ b/docs/site/decisions/Architecture-decisions.md @@ -1,5 +1,3 @@ -# Architecture Decision Records - This section contains the architecture decisions that have been reviewed and generally agreed upon ## What is an ADR? @@ -11,6 +9,6 @@ This section contains the architecture decisions that have been reviewed and gen ## Crafting a new ADR -1. Use the [template](./_template.md) +1. Use the [template](/decisions/template.md) 2. Create the Pull request and gather feedback -3. Retreive your adr-number (see: [numbering](./03-adr-numbering-process.md)) +3. Retreive your adr-number (see: [numbering](/decisions/03-adr-numbering-process.md)) diff --git a/docs/site/decisions/_template.md b/docs/site/decisions/template.md similarity index 93% rename from docs/site/decisions/_template.md rename to docs/site/decisions/template.md index c17fe0272..5c7d6fe68 100644 --- a/docs/site/decisions/_template.md +++ b/docs/site/decisions/template.md @@ -1,4 +1,4 @@ -# Decision record template by Michael Nygard +## Decision record template by Michael Nygard This is the template in [Documenting architecture decisions - Michael Nygard](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions). You can use [adr-tools](https://github.com/npryce/adr-tools) for managing the ADR files. diff --git a/docs/site/guides/services/community.md b/docs/site/guides/services/community.md index ba2687feb..56bda9e14 100644 --- a/docs/site/guides/services/community.md +++ b/docs/site/guides/services/community.md @@ -3,9 +3,9 @@ ## Service Module Specification This section explains how to author a clan service module. -We discussed the initial architecture in [01-clan-service-modules](../../decisions/01-ClanModules.md) and decided to rework the format. +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/clanServices/clan-service-author-interface.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/clanServices/clan-service-author-interface.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) -- [Migration Guide from ClanModules to ClanServices](../migrations/migrate-inventory-services.md) -- [Decision that lead to ClanServices](../../decisions/01-ClanModules.md) +- [Reference Documentation for Service Authors](/reference/clanServices/clan-service-author-interface.md) +- [Migration Guide from ClanModules to ClanServices](/guides/migrations/migrate-inventory-services.md) +- [Decision that lead to ClanServices](/decisions/01-Clan-Modules.md)