Update doc generation with templates and checked via github actions (#86

)

- Update docs (now with templates!)
- Add github action for checking doc changes are committed

.github/workflows/pr.yml

@@ -27,6 +27,30 @@ jobs:
     - name: Format all .tf files recursively
       run: |
         terraform fmt -check -diff -recursive ${{ github.workspace }}
+  terraform_docs:
+    name: Run tfplugindocs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          persist-credentials: false
+
+      - name: Setup tfplugindocs
+        run: |
+          cd /tmp
+          curl -L -o tfplugindocs.zip https://github.com/hashicorp/terraform-plugin-docs/releases/download/v0.9.0/tfplugindocs_0.9.0_linux_amd64.zip
+          unzip tfplugindocs.zip
+          chmod +x tfplugindocs
+
+      - name: Compare generated files with checked in files
+        run: |
+          rm -r docs
+          /tmp/tfplugindocs
+          git diff --stat --exit-code ./docs
   terraform_lint:
 
     name: Run terraform-lint

DEVELOPMENT.md

@@ -27,3 +27,13 @@ provider_installation {
 ```
 
 3) Import the module in another project pinned to the version that matches `.version`. Delete any terraform lock files and run `terraform init`. 
+
+## Updating docs
+
+Documentation files in `docs` are generated from the template files found in `templates`. Any edits to documentation files should be
+made in the `templates` directory. Then you can use the following steps to generate the files:
+
+1) Download `tfplugindocs` from https://github.com/hashicorp/terraform-plugin-docs/releases and make it available on your `PATH`
+2) Run `$ tfplugindocs` from the root of this directory
+
+Note that there is a github action that will prevent merging if the `docs` files checked in do not match the generated ones.

docs/resources/alerting_rule.md

@@ -3,12 +3,12 @@
 page_title: "lightstep_alerting_rule Resource - terraform-provider-lightstep"
 subcategory: ""
 description: |-
-  
+
 ---
 
 # lightstep_alerting_rule (Resource)
 
-Provides a (Lightstep Alerting Rule)[https://api-docs.lightstep.com/reference/listalertingrules]. This can be used to create and manage Lightstep alerting rules.
+Provides a [Lightstep Alerting Rule](https://api-docs.lightstep.com/reference/listalertingrules). This can be used to create and manage Lightstep alerting rules.
 
 ## Example Usage
 
@@ -26,13 +26,11 @@ resource "lightstep_alerting_rule" "beemo_ops_alerting_rule" {
 
 ### Required
 
-- **condition_id** (String)
-- **destination_id** (String)
-- **project_name** (String)
-- **update_interval** (String)
-
-### Optional
-
-- **id** (String) The ID of this resource.
+- `condition_id` (String)
+- `destination_id` (String)
+- `project_name` (String)
+- `update_interval` (String)
 
+### Read-Only
 
+- `id` (String) The ID of this resource.

docs/resources/metric_dashboard.md

@@ -8,7 +8,7 @@ description: |-
 
 # lightstep_metric_dashboard (Resource)
 
-Provides a (Lightstep Metric Dashboard)[https://api-docs.lightstep.com/reference/listmetricdashboardid]. This can be used to create and manage Lightstep Metric Dashboards.
+Provides a [Lightstep Metric Dashboard](https://api-docs.lightstep.com/reference/listmetricdashboardid). This can be used to create and manage Lightstep Metric Dashboards.
 
 
 ## Example Usage
@@ -129,15 +129,15 @@ Optional:
 - `metric` (String)
 - `spans` (Block List, Max: 1) (see [below for nested schema](#nestedblock--chart--query--spans))
 - `timeseries_operator` (String)
-- `timeseries_operator_input_window_ms` (Number)
+- `timeseries_operator_input_window_ms` (Number) Unit specified in milliseconds, but must be at least 30,000 and a round number of seconds (i.e. evenly divisible by 1,000)
 - `tql` (String)
 
 <a id="nestedblock--chart--query--final_window_operation"></a>
 ### Nested Schema for `chart.query.final_window_operation`
 
 Optional:
 
-- `input_window_ms` (Number)
+- `input_window_ms` (Number) Unit specified in milliseconds, but must be at least 30,000 and a round number of seconds (i.e. evenly divisible by 1,000)
 - `operator` (String)
 
 

docs/resources/pagerduty_destination.md

@@ -3,12 +3,12 @@
 page_title: "lightstep_pagerduty_destination Resource - terraform-provider-lightstep"
 subcategory: ""
 description: |-
-  
+
 ---
 
 # lightstep_pagerduty_destination (Resource)
 
-Provides a (Lightstep PagerDuty Alert Destination)[https://api-docs.lightstep.com/reference/postdestinationid]. This can be used to create and manage Lightstep PagerDuty Alert Destinations.
+Provides a [Lightstep PagerDuty Alert Destination](https://api-docs.lightstep.com/reference/postdestinationid). This can be used to create and manage Lightstep PagerDuty Alert Destinations.
 
 ## Example Usage
 
@@ -25,12 +25,10 @@ resource "lightstep_pagerduty_destination" "pd" {
 
 ### Required
 
-- **destination_name** (String) Lightstep destination name
-- **integration_key** (String) PagerDuty Service Integration Key. To create one follow the docs here - https://support.pagerduty.com/docs/services-and-integrations#add-integrations-to-an-existing-service
-- **project_name** (String) Lightstep project name
-
-### Optional
-
-- **id** (String) The ID of this resource.
+- `destination_name` (String) Lightstep destination name
+- `integration_key` (String) PagerDuty Service Integration Key. To create one follow the docs here - https://support.pagerduty.com/docs/services-and-integrations#add-integrations-to-an-existing-service
+- `project_name` (String) Lightstep project name
 
+### Read-Only
 
+- `id` (String) The ID of this resource.

docs/resources/slack_destination.md

@@ -3,12 +3,12 @@
 page_title: "lightstep_slack_destination Resource - terraform-provider-lightstep"
 subcategory: ""
 description: |-
-  
+
 ---
 
 # lightstep_slack_destination (Resource)
 
-Provides a (Lightstep Slack Alert Destination)[https://api-docs.lightstep.com/reference/postdestinationid]. This can be used to create and manage Lightstep Slack Alert Destinations.
+Provides a [Lightstep Slack Alert Destination](https://api-docs.lightstep.com/reference/postdestinationid). This can be used to create and manage Lightstep Slack Alert Destinations.
 
 ## Example Usage
 
@@ -24,11 +24,9 @@ resource "lightstep_slack_destination" "slack" {
 
 ### Required
 
-- **channel** (String) One of: slack channel name (#channel), channel ID, handle name (@user).
-- **project_name** (String) Lightstep project name
-
-### Optional
-
-- **id** (String) The ID of this resource.
+- `channel` (String) One of: slack channel name (#channel), channel ID, handle name (@user).
+- `project_name` (String) Lightstep project name
 
+### Read-Only
 
+- `id` (String) The ID of this resource.

docs/resources/stream.md

@@ -3,12 +3,12 @@
 page_title: "lightstep_stream Resource - terraform-provider-lightstep"
 subcategory: ""
 description: |-
-  
+
 ---
 
 # lightstep_stream (Resource)
 
-Provides a (Lightstep Stream)[https://api-docs.lightstep.com/reference/streams]. This can be used to create and manage Lightstep Streams.
+Provides a [Lightstep Stream](https://api-docs.lightstep.com/reference/streams). This can be used to create and manage Lightstep Streams.
 
 ## Example Usage
 
@@ -32,21 +32,22 @@ resource "lightstep_stream" "custom_data" {
 
 ### Required
 
-- **project_name** (String)
-- **query** (String)
-- **stream_name** (String)
+- `project_name` (String)
+- `query` (String)
+- `stream_name` (String)
 
 ### Optional
 
-- **custom_data** (List of Map of String)
-- **id** (String) The ID of this resource.
-- **timeouts** (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
+- `custom_data` (List of Map of String)
+- `timeouts` (Block, Optional) (see [below for nested schema](#nestedblock--timeouts))
+
+### Read-Only
+
+- `id` (String) The ID of this resource.
 
 <a id="nestedblock--timeouts"></a>
 ### Nested Schema for `timeouts`
 
 Optional:
 
-- **create** (String)
-
-
+- `create` (String)

docs/resources/stream_condition.md

@@ -3,12 +3,12 @@
 page_title: "lightstep_stream_condition Resource - terraform-provider-lightstep"
 subcategory: ""
 description: |-
-  
+
 ---
 
 # lightstep_stream_condition (Resource)
 
-Provides a (Lightstep Stream Condition)[https://api-docs.lightstep.com/reference/conditions]. This can be used to create and manage Lightstep Stream Conditions.
+Provides a [Lightstep Stream Condition](https://api-docs.lightstep.com/reference/conditions). This can be used to create and manage Lightstep Stream Conditions.
 
 ## Example Usage
 
@@ -27,14 +27,12 @@ resource "lightstep_stream_condition" "beemo_errors" {
 
 ### Required
 
-- **condition_name** (String)
-- **evaluation_window_ms** (Number)
-- **expression** (String)
-- **project_name** (String)
-- **stream_id** (String)
-
-### Optional
-
-- **id** (String) The ID of this resource.
+- `condition_name` (String)
+- `evaluation_window_ms` (Number)
+- `expression` (String)
+- `project_name` (String)
+- `stream_id` (String)
 
+### Read-Only
 
+- `id` (String) The ID of this resource.

docs/resources/stream_dashboard.md

@@ -0,0 +1,2 @@
+---
+Stream Dashboards are deprecated and will be removed shortly. DO NOT USE.

docs/resources/webhook_destination.md

@@ -3,12 +3,12 @@
 page_title: "lightstep_webhook_destination Resource - terraform-provider-lightstep"
 subcategory: ""
 description: |-
-  
+
 ---
 
 # lightstep_webhook_destination (Resource)
 
-Provides a (Lightstep Webhook Alert Destination)[https://api-docs.lightstep.com/reference/postdestinationid]. This can be used to create and manage Lightstep Webhook Alert Destinations.
+Provides a [Lightstep Webhook Alert Destination](https://api-docs.lightstep.com/reference/postdestinationid). This can be used to create and manage Lightstep Webhook Alert Destinations.
 
 ```hcl
 resource "lightstep_webhook_destination" "webhook" {
@@ -23,20 +23,20 @@ resource "lightstep_webhook_destination" "webhook" {
 }
 ```
 
-
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- **destination_name** (String)
-- **project_name** (String)
-- **url** (String)
+- `destination_name` (String) Name of the webhook destination
+- `project_name` (String)
+- `url` (String) Webhook URL
 
 ### Optional
 
-- **custom_headers** (Map of String)
-- **template** (String) Payload template for webhook body.
-- **id** (String) The ID of this resource.
+- `custom_headers` (Map of String) Custom HTTP headers for the webhook request
+- `template` (String) Webhook payload body text template. Used for customing webhook messages
 
+### Read-Only
 
+- `id` (String) The ID of this resource.

templates/resources/alerting_rule.md.tmpl

@@ -0,0 +1,24 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "lightstep_alerting_rule Resource - terraform-provider-lightstep"
+subcategory: ""
+description: |-
+
+---
+
+# lightstep_alerting_rule (Resource)
+
+Provides a [Lightstep Alerting Rule](https://api-docs.lightstep.com/reference/listalertingrules). This can be used to create and manage Lightstep alerting rules.
+
+## Example Usage
+
+```hcl
+resource "lightstep_alerting_rule" "beemo_ops_alerting_rule" {
+  project_name    = var.project
+  condition_id    = lightstep_stream_condition.beemo_ops.id
+  destination_id  = lightstep_slack_destination.slack.id
+  update_interval = "1h"
+}
+```
+
+{{ .SchemaMarkdown | trimspace }}

templates/resources/metric_dashboard.md.tmpl

@@ -8,7 +8,7 @@ description: |-
 
 # lightstep_metric_dashboard (Resource)
 
-Provides a (Lightstep Metric Dashboard)[https://api-docs.lightstep.com/reference/listmetricdashboardid]. This can be used to create and manage Lightstep Metric Dashboards.
+Provides a [Lightstep Metric Dashboard](https://api-docs.lightstep.com/reference/listmetricdashboardid). This can be used to create and manage Lightstep Metric Dashboards.
 
 
 ## Example Usage

templates/resources/pagerduty_destination.md.tmpl

@@ -0,0 +1,23 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "lightstep_pagerduty_destination Resource - terraform-provider-lightstep"
+subcategory: ""
+description: |-
+
+---
+
+# lightstep_pagerduty_destination (Resource)
+
+Provides a [Lightstep PagerDuty Alert Destination](https://api-docs.lightstep.com/reference/postdestinationid). This can be used to create and manage Lightstep PagerDuty Alert Destinations.
+
+## Example Usage
+
+```hcl
+resource "lightstep_pagerduty_destination" "pd" {
+  project_name     = var.project
+  destination_name = "My Destination"
+  integration_key  = var.pd_integration_key
+}
+```
+
+{{ .SchemaMarkdown | trimspace }}

templates/resources/slack_destination.md.tmpl

@@ -0,0 +1,22 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "lightstep_slack_destination Resource - terraform-provider-lightstep"
+subcategory: ""
+description: |-
+
+---
+
+# lightstep_slack_destination (Resource)
+
+Provides a [Lightstep Slack Alert Destination](https://api-docs.lightstep.com/reference/postdestinationid). This can be used to create and manage Lightstep Slack Alert Destinations.
+
+## Example Usage
+
+```hcl
+resource "lightstep_slack_destination" "slack" {
+  project_name = var.project
+  channel      = "#urgent-care"
+}
+```
+
+{{ .SchemaMarkdown | trimspace }}