From 7c1920f55e86717c1979dd63a87bfec95fc4af73 Mon Sep 17 00:00:00 2001
From: Mauritz Uphoff <39736813+h3adex@users.noreply.github.com>
Date: Wed, 3 Sep 2025 10:23:44 +0200
Subject: [PATCH] chore(docs): improve docs for image_v2 and machine_type
 (#977)

* chore(docs): improve docs for image_v2 and machine_type

Signed-off-by: Mauritz Uphoff <mauritz.uphoff@stackit.cloud>

* review changes

Signed-off-by: Mauritz Uphoff <mauritz.uphoff@stackit.cloud>

---------

Signed-off-by: Mauritz Uphoff <mauritz.uphoff@stackit.cloud>
---
 docs/data-sources/image_v2.md                 | 10 ++++++++++
 docs/data-sources/machine_type.md             |  8 +++++++-
 .../services/iaas/imagev2/datasource.go       |  4 ++++
 .../services/iaas/machinetype/datasource.go   | 20 ++++++++++---------
 4 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/docs/data-sources/image_v2.md b/docs/data-sources/image_v2.md
index 12ad0f02..43f713ac 100644
--- a/docs/data-sources/image_v2.md
+++ b/docs/data-sources/image_v2.md
@@ -20,6 +20,10 @@ description: |-
     }
   }
   
+  You can also list available images using the STACKIT CLI https://github.com/stackitcloud/stackit-cli:
+  
+  stackit image list
+  
   ~> This datasource is in beta and may be subject to breaking changes in the future. Use with caution. See our guide https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs/guides/opting_into_beta_resources for how to opt-in to use beta resources.
 ---
 
@@ -47,6 +51,12 @@ resource "stackit_server" "example" {
 }
 ```
 
+You can also list available images using the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli):
+
+```bash
+stackit image list
+```
+
 ~> This datasource is in beta and may be subject to breaking changes in the future. Use with caution. See our [guide](https://registry.terraform.io/providers/stackitcloud/stackit/latest/docs/guides/opting_into_beta_resources) for how to opt-in to use beta resources.
 
 ## Example Usage
diff --git a/docs/data-sources/machine_type.md b/docs/data-sources/machine_type.md
index 2faa8da4..10f80fc3 100644
--- a/docs/data-sources/machine_type.md
+++ b/docs/data-sources/machine_type.md
@@ -52,7 +52,13 @@ Examples:
 - extraSpecs.cpu == "intel-icelake-generic"
 - extraSpecs.cpu == "intel-icelake-generic" && vcpus == 2
 
-See https://expr-lang.org/docs/language-definition for syntax.
+Syntax reference: https://expr-lang.org/docs/language-definition
+
+You can also list available machine-types using the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli):
+
+```bash
+stackit server machine-type list
+```
 - `project_id` (String) STACKIT Project ID.
 
 ### Optional
diff --git a/stackit/internal/services/iaas/imagev2/datasource.go b/stackit/internal/services/iaas/imagev2/datasource.go
index ab364bb0..e3956239 100644
--- a/stackit/internal/services/iaas/imagev2/datasource.go
+++ b/stackit/internal/services/iaas/imagev2/datasource.go
@@ -178,6 +178,10 @@ func (d *imageDataV2Source) Schema(_ context.Context, _ datasource.SchemaRequest
 			"    ignore_changes = [boot_volume[0].source_id]\n"+
 			"  }\n"+
 			"}\n"+
+			"```\n\n"+
+			"You can also list available images using the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli):\n\n"+
+			"```bash\n"+
+			"stackit image list\n"+
 			"```",
 	), core.Datasource)
 	resp.Schema = schema.Schema{
diff --git a/stackit/internal/services/iaas/machinetype/datasource.go b/stackit/internal/services/iaas/machinetype/datasource.go
index 7bc9ce55..ed2c1c9d 100644
--- a/stackit/internal/services/iaas/machinetype/datasource.go
+++ b/stackit/internal/services/iaas/machinetype/datasource.go
@@ -92,15 +92,17 @@ func (d *machineTypeDataSource) Schema(_ context.Context, _ datasource.SchemaReq
 				Optional:    true,
 			},
 			"filter": schema.StringAttribute{
-				Description: `Expr-lang filter for filtering machine types.
-
-Examples:
-- vcpus == 2
-- ram >= 2048
-- extraSpecs.cpu == "intel-icelake-generic"
-- extraSpecs.cpu == "intel-icelake-generic" && vcpus == 2
-
-See https://expr-lang.org/docs/language-definition for syntax.`,
+				Description: "Expr-lang filter for filtering machine types.\n\n" +
+					"Examples:\n" +
+					"- vcpus == 2\n" +
+					"- ram >= 2048\n" +
+					"- extraSpecs.cpu == \"intel-icelake-generic\"\n" +
+					"- extraSpecs.cpu == \"intel-icelake-generic\" && vcpus == 2\n\n" +
+					"Syntax reference: https://expr-lang.org/docs/language-definition\n\n" +
+					"You can also list available machine-types using the [STACKIT CLI](https://github.com/stackitcloud/stackit-cli):\n\n" +
+					"```bash\n" +
+					"stackit server machine-type list\n" +
+					"```",
 				Required: true,
 			},
 			"description": schema.StringAttribute{