Introduce templates for docs (#56)

This commit introduces templates for generating provider documentation. There's also a new generic resource page with information regarding all resources, including the ones we do not support in the provider (SLO annotations and Alert Silences)
nobl9 · Dec 5, 2022 · 4e41eed · 4e41eed
1 parent 42da027
commit 4e41eed
Show file tree

Hide file tree

Showing 58 changed files with 1,073 additions and 276 deletions.
diff --git a/.golangci.yml b/.golangci.yml
@@ -31,7 +31,7 @@ linters-settings:
     # Report about shadowed variables.
     check-shadowing: true
   lll:
-    line-length: 120
+    line-length: 250
   gocritic:
     enabled-tags:
       # - diagnostic

diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
@@ -0,0 +1,37 @@
+# Documentation
+
+[Official Terraform Provider Documentation](https://www.terraform.io/registry/providers/docs)
+
+This section provides all the information needed to work with `terraform-provider-nobl9` documentation.
+
+## Tool
+
+Documentation is created using the [tfplugindocs](https://github.com/hashicorp/terraform-plugin-docs) tool.
+
+## Which files should I change?
+
+- Update (if needed) templates available under `templates/` directory
+  - Each resource has a separate template file, ex. `templates/resources/slo.md.tmpl`
+  - We use generic templates for index and resource pages: `templates/index.md.tmpl` and `templates/resources.md.tmpl` 
+  - Use Data Fields supported by tfplugindocs - https://github.com/hashicorp/terraform-plugin-docs
+- Update (if needed) examples available under `examples/` directory
+  - Make sure that all examples are working with the latest version of the provider
+  - `examples/provider/provider.tf` is the example that will be rendered on the main page on [provider documentation](https://registry.terraform.io/providers/nobl9/nobl9/latest/docs#schema)
+  - `examples/resources/<resource_name>/resource.tf` will be rendered for every resource on their documentation page, ex. https://registry.terraform.io/providers/nobl9/nobl9/latest/docs/resources/slo
+- Update (if needed) `"description"` field for a resource, ex. in `nobl9/resource_slo.go`:
+```
+Schema: map[string]*schema.Schema{
+  ...
+  "description":  "Your new description"
+  ...
+}
+```
+  - This description will be rendered on the documentation page for the changed resource.
+- Do not touch anything under `docs/` directory.
+
+## How to generate docs?
+
+You need to have [Go](https://go.dev/) installed on your machine, then run:
+```
+go generate
+```
diff --git a/docs/index.md b/docs/index.md
@@ -1,16 +1,36 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "nobl9 Provider"
-subcategory: ""
+page_title: "Nobl9 Provider"
 description: |-
-  
+  The Nobl9 provider provides utilities for working with Nobl9 API.
 ---
 
-# nobl9 Provider
+# NOBL9 Provider
 
+There are many types of [resources](https://docs.nobl9.com/#using-resources-in-nobl9) in the Nobl9 platform. You can configure them via:
+- UI (https://app.nobl9.com)
+- [sloctl](https://docs.nobl9.com/sloctl-user-guide/)
+- Nobl9 Terraform Provider
 
+## Scope of Support
 
-## Example Usage
+The Nobl9 Provider delivers tools working with the Nobl9 API to create and manage the following resources:
+- SLOs
+- Services
+- Projects
+- Alert Policies
+- Alert Methods
+- Data Sources
+- Role Bindings
+
+The Nobl9 Terraform Provider does not support the configuration of the following resources:
+- [SLO Annotations](https://docs.nobl9.com/Features/SLO_Annotations/)
+- [Alert Silence](https://docs.nobl9.com/Alert_Methods/Alert_silence/)
+
+## Configuration
+
+To start using Nobl9 Terraform Provider, you must configure the provider with the proper credentials. Then, use the navigation on the left to learn more about the available resources.
+
+The following is an exemplary configuration:
 
 ```terraform
 terraform {
@@ -35,13 +55,19 @@ provider "nobl9" {
 
 ### Required
 
-- `client_id` (String) Authentication parameter ClientID.
-- `client_secret` (String, Sensitive) Authentication parameter ClientSecret.
-- `organization` (String) Nobl9 Organization that contain resources managed by this provider.
+- `client_id` (String) the [Client ID](https://docs.nobl9.com/sloctl-user-guide/#configuration) of your Nobl9 account required to connect to Nobl9.
+- `client_secret` (String, Sensitive) the [Client Secret](https://docs.nobl9.com/sloctl-user-guide/#configuration) of your Nobl9 account required to connect to Nobl9.
+- `organization` (String) Nobl9 [Organization ID](https://docs.nobl9.com/API_Documentation/api-endpoints-for-slo-annotations/#common-headers) that contains resources managed by the Nobl9 Terraform provider.
 - `project` (String) Nobl9 project used when importing resources.
 
 ### Optional
 
 - `ingest_url` (String) Nobl9 API URL.
 - `okta_auth_server` (String) Authorization service configuration.
 - `okta_org_url` (String) Authorization service URL.
+
+## Useful Links
+
+[Nobl9 Documentation](https://docs.nobl9.com/)
+
+[Nobl9 Terraform Provider Release Notes](https://github.com/nobl9/terraform-provider-nobl9/releases)
diff --git a/docs/resources/agent.md b/docs/resources/agent.md
@@ -1,22 +1,24 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "nobl9_agent Resource - terraform-provider-nobl9"
-subcategory: ""
 description: |-
-  Agent configuration documentation https://docs.nobl9.com/nobl9_agent
+  Agent configuration | Nobl9 Documentation https://docs.nobl9.com/nobl9_agent
 ---
 
 # nobl9_agent (Resource)
 
-[Agent configuration documentation](https://docs.nobl9.com/nobl9_agent)
+The Agent is a lightweight application that executes the queries defined for your Nobl9 SLOs. Queries are written in the language supported by the data source in question and executed via native APIs.
+
+The Agent then sends your SLI metrics back to Nobl9 for processing and error budget calculation.
+
+For more information, refer to [Agent configuration | Nobl9 Documentation](https://docs.nobl9.com/nobl9_agent)
 
 ## Example Usage
 
 ```terraform
 resource "nobl9_project" "this" {
-  display_name = "Test Terraform"
-  name         = "test-terraform"
-  description  = "An example terraform project"
+  display_name = "Test N9 Terraform"
+  name         = "test-n9-terraform"
+  description  = "An example N9 Terraform project"
 }
 
 resource "nobl9_agent" "this" {
@@ -35,9 +37,9 @@ resource "nobl9_agent" "this" {
 
 ### Required
 
-- `agent_type` (String) Type of an agent. [Supported agent types](https://docs.nobl9.com/Sources/)
-- `name` (String) Unique name of the resource. Must match [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
-- `project` (String) Name of the project the resource is in. Must match [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
+- `agent_type` (String) The type of the Agent. Check [Supported Agent types | Nobl9 Documentation](https://docs.nobl9.com/Sources/)
+- `name` (String) Unique name of the resource, must conform to the naming convention from [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
+- `project` (String) Name of the Nobl9 project the resource sits in, must conform to the naming convention from [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
 - `source_of` (List of String) Source of Metrics and/or Services
 
 ### Optional
@@ -47,8 +49,8 @@ resource "nobl9_agent" "this" {
 - `bigquery_config` (Block Set, Max: 1) [Configuration documentation](https://docs.nobl9.com/Sources/bigquery#bigquery-agent) (see [below for nested schema](#nestedblock--bigquery_config))
 - `cloudwatch_config` (Block Set, Max: 1) [Configuration documentation](https://docs.nobl9.com/Sources/Amazon_CloudWatch/#cloudwatch-agent) (see [below for nested schema](#nestedblock--cloudwatch_config))
 - `datadog_config` (Block Set, Max: 1) [Configuration documentation](https://docs.nobl9.com/Sources/datadog#datadog-agent) (see [below for nested schema](#nestedblock--datadog_config))
-- `description` (String) Optional description of the resource.
-- `display_name` (String) Display name of the resource.
+- `description` (String) Optional description of the resource. Here, you can add details about who is responsible for the integration (team/owner) or the purpose of creating it.
+- `display_name` (String) User-friendly display name of the resource.
 - `dynatrace_config` (Block Set, Max: 1) [Configuration documentation](https://docs.nobl9.com/Sources/dynatrace#dynatrace-agent) (see [below for nested schema](#nestedblock--dynatrace_config))
 - `elasticsearch_config` (Block Set, Max: 1) [Configuration documentation](https://docs.nobl9.com/Sources/elasticsearch#elasticsearch-agent) (see [below for nested schema](#nestedblock--elasticsearch_config))
 - `gcm_config` (Block Set, Max: 1) [Configuration documentation](https://docs.nobl9.com/Sources/google-cloud-monitoring#google-cloud-monitoring-agent) (see [below for nested schema](#nestedblock--gcm_config))
@@ -70,14 +72,14 @@ resource "nobl9_agent" "this" {
 ### Read-Only
 
 - `id` (String) The ID of this resource.
-- `status` (Map of String) Status of created agent.
+- `status` (Map of String) Status of the created agent.
 
 <a id="nestedblock--amazon_prometheus_config"></a>
 ### Nested Schema for `amazon_prometheus_config`
 
 Required:
 
-- `region` (String) AWS region ex. eu-central-1
+- `region` (String) AWS region e.g., eu-central-1
 - `url` (String) Base URL to Amazon Prometheus server.
 
 
@@ -86,7 +88,7 @@ Required:
 
 Required:
 
-- `url` (String) Base URL to a AppDynamics Controller.
+- `url` (String) Base URL to the AppDynamics Controller.
 
 
 <a id="nestedblock--bigquery_config"></a>
@@ -102,7 +104,7 @@ Required:
 
 Required:
 
-- `site` (String) `com` or `eu`, Datadog SaaS instance, which corresponds to one of their two locations (https://www.datadoghq.com/ in the U.S. or https://datadoghq.eu/ in the European Union)
+- `site` (String) `com` or `eu`, Datadog SaaS instance, which corresponds to one of Datadog's two locations (https://www.datadoghq.com/ in the U.S. or https://datadoghq.eu/ in the European Union)
 
 
 <a id="nestedblock--dynatrace_config"></a>
@@ -118,7 +120,7 @@ Required:
 
 Required:
 
-- `url` (String) API URL endpoint of Elasticsearch's instance.
+- `url` (String) API URL endpoint to the Elasticsearch's instance.
 
 
 <a id="nestedblock--gcm_config"></a>
@@ -130,31 +132,31 @@ Required:
 
 Required:
 
-- `url` (String) API URL endpoint of Grafana Loki instance.
+- `url` (String) API URL endpoint to the Grafana Loki instance.
 
 
 <a id="nestedblock--graphite_config"></a>
 ### Nested Schema for `graphite_config`
 
 Required:
 
-- `url` (String) API URL endpoint of Graphite's instance.
+- `url` (String) API URL endpoint to the Graphite's instance.
 
 
 <a id="nestedblock--influxdb_config"></a>
 ### Nested Schema for `influxdb_config`
 
 Required:
 
-- `url` (String) API URL endpoint of InfluxDB's instance.
+- `url` (String) API URL endpoint to the InfluxDB's instance.
 
 
 <a id="nestedblock--instana_config"></a>
 ### Nested Schema for `instana_config`
 
 Required:
 
-- `url` (String) API URL endpoint of InfluxDB's instance.
+- `url` (String) API URL endpoint to the InfluxDB's instance.
 
 
 <a id="nestedblock--lightstep_config"></a>
@@ -171,7 +173,7 @@ Required:
 
 Required:
 
-- `account_id` (String) ID number assigned to the New Relic user account
+- `account_id` (String) ID number assigned to the New Relic user account.
 
 
 <a id="nestedblock--opentsdb_config"></a>
@@ -203,7 +205,7 @@ Required:
 
 Required:
 
-- `url` (String) Base API URL of the Splunk Search app.
+- `url` (String) Base API URL to the Splunk Search app.
 
 
 <a id="nestedblock--splunk_observability_config"></a>
@@ -219,10 +221,12 @@ Required:
 
 Required:
 
-- `url` (String) Base API URL of the Splunk Search app.
+- `url` (String) Base API URL to the Splunk Search app.
 
 
 <a id="nestedblock--thousandeyes_config"></a>
 ### Nested Schema for `thousandeyes_config`
 
+## Nobl9 Official Documentation
 
+https://docs.nobl9.com/
diff --git a/docs/resources/alert_method_discord.md b/docs/resources/alert_method_discord.md
@@ -1,33 +1,50 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "nobl9_alert_method_discord Resource - terraform-provider-nobl9"
-subcategory: ""
+subcategory: "Alert Methods"
 description: |-
-  Integration configuration documentation https://docs.nobl9.com/Alert_Methods/discord
+  Discord Alert Method | Nobl9 Documentation https://docs.nobl9.com/Alert_Methods/discord
 ---
 
 # nobl9_alert_method_discord (Resource)
 
-[Integration configuration documentation](https://docs.nobl9.com/Alert_Methods/discord)
+The **Discord Alert Method** enables sending alerts through Discord to notify Nobl9 users whenever an incident is triggered.
 
+For more details, refer to [Discord Alert Method | Nobl9 Documentation](https://docs.nobl9.com/Alert_Methods/discord).
 
+## Example Usage
+
+Here's an example of Discord Terraform resource configuration:
+
+```terraform
+resource "nobl9_alert_method_discord" "this" {
+  name         = "my-discord-alert"
+  display_name = "My Discord alert"
+  project      = "My Discord alert"
+  description = "My Discord alert method"
+  url         = "https://discord.webhook.url"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `name` (String) Unique name of the resource. Must match [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
-- `project` (String) Name of the project the resource is in. Must match [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
+- `name` (String) Unique name of the resource, must conform to the naming convention from [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
+- `project` (String) Name of the Nobl9 project the resource sits in, must conform to the naming convention from [DNS RFC1123](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names).
 
 ### Optional
 
-- `description` (String) Optional description of the resource.
-- `display_name` (String) Display name of the resource.
-- `url` (String, Sensitive) Discord webhook endpoint URL.
+- `description` (String) Optional description of the resource. Here, you can add details about who is responsible for the integration (team/owner) or the purpose of creating it.
+- `display_name` (String) User-friendly display name of the resource.
+- `url` (String, Sensitive) Discord webhook endpoint URL. Refer to [Intro to webhooks | Discord documentation](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks) for more details.
 
 ### Read-Only
 
 - `id` (String) The ID of this resource.
 
+## Useful Links
+
+[Discord alerts configuration | Nobl9 Documentation](https://docs.nobl9.com/Alert_Methods/discord/)
 
+[Intro to webhooks | Discord Documentation](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)