Add examples to data and resource documentation blocks

Documented most of the non-deprecated data sources that are still
missing examples, and some of the resources.

docs/data-sources/app.md

@@ -29,15 +29,16 @@ data "observe_app" "example" {
 
 ### Optional
 
-- `folder` (String) OID of workspace dataset is contained in.
-- `name` (String)
+- `folder` (String) Folder that the app is in. Required if looking up by name.
+- `id` (String) ID of the app. If looking up app, one of name or id must be specified.
+- `name` (String) Generated display name of app.
 
 ### Read-Only
 
-- `description` (String)
-- `id` (String) The ID of this resource.
-- `module_id` (String)
-- `oid` (String)
-- `outputs` (String)
-- `variables` (Map of String)
-- `version` (String)
+- `description` (String) The description of the app. Packaged with the app module.
+- `module_id` (String) Underlying module id for the specific app. Each module_id corresponds with one app.
+- `oid` (String) OID (Observe ID) for this object. This is the canonical identifier that
+should be used when referring to this object in terraform manifests.
+- `outputs` (String) Resources outputted by the app for user consumption
+- `variables` (Map of String) Additional settings to pass to the app.
+- `version` (String) The version of the app to install.

docs/data-sources/default_dashboard.md

@@ -10,16 +10,22 @@ description: |-
 
 Fetches the default dashboard OID for the specified dataset.
 
+## Example Usage
 
+```terraform
+data "observe_default_dashboard" "example" {
+    dataset = "41000100"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `dataset` (String)
+- `dataset` (String) The OID of the dataset that the default dashboard is being set for.
 
 ### Read-Only
 
-- `dashboard` (String)
+- `dashboard` (String) The associated default dashboard.
 - `id` (String) The ID of this resource.

docs/data-sources/folder.md

@@ -10,22 +10,38 @@ description: |-
 
 Fetches data for an existing Observe folder.
 
+## Example Usage
 
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+data "observe_folder" "lookup_by_name" {
+  workspace = data.observe_workspace.default.oid
+  name      = "name_of_a_folder"
+}
+
+data "observe_folder" "lookup_by_id" {
+  id = "41000100"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `workspace` (String)
+- `workspace` (String) OID of the workspace this object is contained in.
 
 ### Optional
 
-- `id` (String) Folder ID. Either `name` or `id` must be provided.
-- `name` (String)
+- `id` (String) Folder ID. For lookup, either name or id must be specified
+- `name` (String) Folder Name. For lookup, either name or id must be specified
 
 ### Read-Only
 
-- `description` (String) Dataset description.
-- `icon_url` (String) Icon image.
-- `oid` (String) The Observe ID for dataset.
+- `description` (String) Description for the folder.
+- `icon_url` (String) Icon to be displayed for this object. Icons are sourced from the [fluency-filled](https://icons8.com/icons/fluency-systems-filled) icon set.
+- `oid` (String) OID (Observe ID) for this object. This is the canonical identifier that
+should be used when referring to this object in terraform manifests.

docs/data-sources/link.md

@@ -10,7 +10,30 @@ description: |-
 
 A link connects two datasets through a resource key.
 
-
+## Example Usage
+
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+data "observe_dataset" "a" {
+  workspace = data.observe_workspace.default.oid
+  name      = "Dataset A"
+}
+
+data "observe_dataset" "b" {
+  workspace = data.observe_workspace.default.oid
+  name      = "Dataset B"
+}
+
+# check that link from dataset a to dataset b on key "key" exists
+data "observe_link" "check" {
+  source = data.observe_dataset.a.oid
+  target = data.observe_dataset.b.oid
+  fields = ["key"]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/monitor.md

@@ -10,7 +10,24 @@ description: |-
 
 Monitors provide a flexible way to alert for patterns in your incoming data. A monitor executes a query periodically and applies rules to determine whether to trigger notifications. Notifications are forwarded to subscribed channels, which in turn route notifications to configured channel actions.
 
-
+## Example Usage
+
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+# lookup by id
+data "observe_monitor" "id_lookup" {
+  id = 41000100
+}
+
+# lookup by name
+data "observe_monitor" "name_lookup" {
+  workspace = data.observe_workspace.default.oid
+  name = "name of the monitor"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/monitor_action.md

@@ -10,7 +10,24 @@ description: |-
 
 Monitors provide a flexible way to alert for patterns in your incoming data. A monitor executes a query periodically and applies rules to determine whether to trigger notifications. Notifications are forwarded to subscribed channels, which in turn route notifications to configured channel actions.
 
-
+## Example Usage
+
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+# lookup by id
+data "observe_monitor_action" "id_lookup" {
+  id = 41000100
+}
+
+# lookup by name
+data "observe_monitor_action" "name_lookup" {
+  workspace = data.observe_workspace.default.oid
+  name = "name of the monitor action"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/monitor_v2.md

@@ -16,7 +16,24 @@ are matched. These alerts can optionally also be forwarded to notification recei
 like email and webhooks using shared or single-monitor actions to configure the
 template and destinations to configure the receiver.
 
-
+## Example Usage
+
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+# lookup by id
+data "observe_monitor_v2" "id_lookup" {
+  id = 41000100
+}
+
+# lookup by name
+data "observe_monitor_v2" "name_lookup" {
+  workspace = data.observe_workspace.default.oid
+  name = "name of the monitor"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/monitor_v2_action.md

@@ -10,25 +10,46 @@ description: |-
 
 
 
+## Example Usage
 
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+# lookup by id
+data "observe_monitor_v2_action" "id_lookup" {
+  id = 41000100
+}
+
+# lookup by name
+data "observe_monitor_v2_action" "name_lookup" {
+  workspace = data.observe_workspace.default.oid
+  name = "name of the monitor action"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Optional
 
-- `name` (String)
-- `workspace` (String)
+- `id` (String) Resource ID for this object.
+ One of either `id` or `name` must be provided.
+- `name` (String) Name of the monitor v2 action.
+ One of either `id` or `name` must be provided.
+- `workspace` (String) OID of the workspace this object is contained in.
+ Must be specified if looking up by name
 
 ### Read-Only
 
-- `description` (String)
+- `description` (String) description for this monitor v2 action.
 - `destination` (String)
-- `email` (Block List) (see [below for nested schema](#nestedblock--email))
-- `id` (String) The ID of this resource.
-- `oid` (String)
-- `type` (String)
-- `webhook` (Block List) (see [below for nested schema](#nestedblock--webhook))
+- `email` (Block List) Configuration settings for email type actions. (see [below for nested schema](#nestedblock--email))
+- `oid` (String) OID (Observe ID) for this object. This is the canonical identifier that
+should be used when referring to this object in terraform manifests.
+- `type` (String) Type of action to take when the associated monitor triggers.
+- `webhook` (Block List) Configuration settings for webhook type actions. (see [below for nested schema](#nestedblock--webhook))
 
 <a id="nestedblock--email"></a>
 ### Nested Schema for `email`

docs/data-sources/oid.md

@@ -10,7 +10,26 @@ description: |-
 
 Parses or formats an Observe OID. To parse an OID, only set the `oid` attribute. To format an OID, set the `type`, `id`, and optionally the `version` attributes. This is a logical data source and does not make any API calls.
 
+## Example Usage
 
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+
+# parse an OID into components
+data "observe_oid" "workspace" {
+  oid = data.observe_workspace.default.oid
+}
+
+# construct an OID from components
+data "observe_oid" "workspace" {
+  id = data.observe_workspace.default.id
+  type = "workspace"
+  version = "1"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/query.md

@@ -10,7 +10,31 @@ description: |-
 
 Queries data stored in Observe and returns the results.
 
-
+## Example Usage
+
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+data "observe_dataset" "a" {
+  workspace = data.observe_workspace.default.oid
+  name      = "Dataset A"
+}
+
+# query on dataset A
+data "observe_query" "query_for_a" {
+  start = timestamp()
+
+  inputs = { "test" = data.observe_dataset.a.oid }
+
+  stage {
+    pipeline = <<-EOF
+      # ... OPAL query
+    EOF
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/data-sources/terraform.md

@@ -10,7 +10,13 @@ description: |-
 
 Generates Terraform configuration for a given resource in Observe. Datasets, monitors, and dashboards are supported.
 
+## Example Usage
 
+```terraform
+data "observe_default_dashboard" "lookup_by_name" {
+    target  = "41000100"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -21,8 +27,8 @@ Generates Terraform configuration for a given resource in Observe. Datasets, mon
 
 ### Read-Only
 
-- `data_source` (String)
+- `data_source` (String) Terraform data_source representation of the specified Observe resource.
 - `id` (String) The ID of this resource.
-- `import_id` (String)
-- `import_name` (String)
-- `resource` (String)
+- `import_id` (String) Observe ID that can be used with terraform import to bring the Observe resource under terraform management.
+- `import_name` (String) Name of the specified resource  that can be used with terraform import to bring the Observe resource under terraform management.
+- `resource` (String) Terraform resource representation of the specified Observe resource.

docs/data-sources/worksheet.md

@@ -10,7 +10,18 @@ description: |-
 
 Fetches metadata for an existing Observe worksheet.
 
-
+## Example Usage
+
+```terraform
+data "observe_workspace" "default" {
+  name = "Default"
+}
+
+data "observe_worksheet" "lookup" {
+  workspace = data.observe_workspace.default.oid
+  id = "41000100"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

docs/resources/app.md

@@ -35,19 +35,20 @@ resource "observe_app" "example" {
 
 ### Required
 
-- `folder` (String)
-- `module_id` (String)
+- `folder` (String) Observe folder OID for this object.
+- `module_id` (String) Underlying module id for the specific app. Each module_id corresponds with one app.
 
 ### Optional
 
-- `variables` (Map of String)
-- `version` (String)
+- `variables` (Map of String) Additional settings to pass to the app.
+- `version` (String) The version of the app to install.
 
 ### Read-Only
 
 - `id` (String) The ID of this resource.
-- `name` (String)
-- `oid` (String)
+- `name` (String) Generated display name of app.
+- `oid` (String) OID (Observe ID) for this object. This is the canonical identifier that
+should be used when referring to this object in terraform manifests.
 - `outputs` (String)
 ## Import
 Import is supported using the following syntax: