From 47b9a1cb7fcb0cf68f2f3fe5648ffbaa23e69f46 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 1 Oct 2024 11:21:30 +0200
Subject: [PATCH] docs: improve flake-parts reference

---
 docs/nix/render_options/__init__.py | 38 ++++++++++++++++++++++++++---
 docs/site/manual/flake-parts.md     |  3 ++-
 2 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/docs/nix/render_options/__init__.py b/docs/nix/render_options/__init__.py
index aacf8f3ef..bbec1df7e 100644
--- a/docs/nix/render_options/__init__.py
+++ b/docs/nix/render_options/__init__.py
@@ -346,12 +346,42 @@ def produce_build_clan_docs() -> None:
 
     output = """# BuildClan
 
-This provides an overview of the available arguments of the `buildClan` function.
+This provides an overview of the available arguments of the `clan` interface.
 
-!!! Note "Flake-parts"
-    Each attribute is also available via `clan.<option>`
+Each attribute is documented below
 
-    For example `clan.inventory = ...;` is equivalent to `buildClan { inventory = ...; }`.
+- **buildClan**: A function that takes an attribute set.`.
+
+    ??? example "buildClan Example"
+
+        ```nix
+        buildClan {
+            directory = self;
+            machines = {
+                jon = { };
+                sara = { };
+            };
+        };
+        ```
+
+- **flake-parts**: Each attribute can be defined via `clan.<attribute name>`. See our [flake-parts](../../manual/flake-parts.md) guide.
+
+    ??? example "flake-parts Example"
+
+        ```nix
+        flake-parts.lib.mkFlake { inherit inputs; } ({
+            systems = [];
+            imports = [
+                clan-core.flakeModules.default
+            ];
+            clan = {
+                machines = {
+                    jon = { };
+                    sara = { };
+                };
+            };
+        });
+        ```
 
 """
     with Path(BUILD_CLAN_PATH).open() as f:
diff --git a/docs/site/manual/flake-parts.md b/docs/site/manual/flake-parts.md
index 86178462d..378bcf6a0 100644
--- a/docs/site/manual/flake-parts.md
+++ b/docs/site/manual/flake-parts.md
@@ -28,7 +28,7 @@ inputs = {
 
 ## 2. Import Clan-Core Flake Module
 
-After updating your flake inputs, the next step is to import the `clan-core` flake module. This will make the [clan options](https://git.clan.lol/clan/clan-core/src/branch/main/flakeModules/clan.nix) available within `mkFlake`.
+After updating your flake inputs, the next step is to import the `clan-core` flake module. This will make the [clan options](../reference/nix-api/buildclan.md) available within `mkFlake`.
 
 ```nix
   outputs =
@@ -61,6 +61,7 @@ Below is a guide on how to structure this in your flake.nix:
         clan-core.flakeModules.default
       ];
       # Define your clan
+      # See: https://docs.clan.lol/reference/nix-api/buildclan/
       clan = {
         # Clan wide settings. (Required)
         meta.name = ""; # Ensure to choose a unique name.