Merge pull request #23 from datastax/docs-love

Docs Improvements
datastax · May 24, 2021 · 5669d6a · 5669d6a
2 parents 787ff07 + 9a656b5
commit 5669d6a
Show file tree

Hide file tree

Showing 26 changed files with 117 additions and 36 deletions.
diff --git a/...-sources/data_source_available_regions.md → docs/data-sources/available_regions.md b/...-sources/data_source_available_regions.md → docs/data-sources/available_regions.md
@@ -1,16 +1,21 @@
 ---
 # generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "astra_data_source_available_regions Data Source - terraform-provider-astra"
+page_title: "astra_available_regions Data Source - terraform-provider-astra"
 subcategory: ""
 description: |-
   Retrieve a list of available cloud regions in Astra
 ---
 
-# astra_data_source_available_regions (Data Source)
+# astra_available_regions (Data Source)
 
 Retrieve a list of available cloud regions in Astra
 
+## Example Usage
 
+```terraform
+data "astra_data_source_available_regions" "regions" {
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/data-sources/database.md b/docs/data-sources/database.md
@@ -3,14 +3,20 @@
 page_title: "astra_database Data Source - terraform-provider-astra"
 subcategory: ""
 description: |-
-  Datasource for Astra database.
+  astra_database provides a datasource for Astra an Astra database. This can be used to select an existing database within your Astra Organization.
 ---
 
 # astra_database (Data Source)
 
-Datasource for Astra database.
+`astra_database` provides a datasource for Astra an Astra database. This can be used to select an existing database within your Astra Organization.
 
+## Example Usage
 
+```terraform
+data "astra_database" "db" {
+  database_id = "8d356587-73b3-430a-9c0e-d780332e2afb"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/data-sources/databases.md b/docs/data-sources/databases.md
@@ -3,14 +3,24 @@
 page_title: "astra_databases Data Source - terraform-provider-astra"
 subcategory: ""
 description: |-
-  Retrieve a list of Astra databases.
+  astra_databases provides a datasource for a list of Astra databases. This can be used to select databases within your Astra Organization.
 ---
 
 # astra_databases (Data Source)
 
-Retrieve a list of Astra databases.
+`astra_databases` provides a datasource for a list of Astra databases. This can be used to select databases within your Astra Organization.
 
+## Example Usage
 
+```terraform
+data "astra_databases" "databaselist" {
+  status = "ACTIVE"
+}
+
+output "existing_dbs" {
+  value = [for db in data.astra_databases.databaselist.results : db.id]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/data-sources/keyspace.md b/docs/data-sources/keyspace.md
@@ -3,14 +3,21 @@
 page_title: "astra_keyspace Data Source - terraform-provider-astra"
 subcategory: ""
 description: |-
-  Keyspace for an Astra database.
+  astra_keyspace provides a datasource for a particular keyspace. See astra_keyspaces if you're looking to fetch all the keyspaces for a particular database.
 ---
 
 # astra_keyspace (Data Source)
 
-Keyspace for an Astra database.
+`astra_keyspace` provides a datasource for a particular keyspace. See `astra_keyspaces` if you're looking to fetch all the keyspaces for a particular database.
 
+## Example Usage
 
+```terraform
+data "astra_keyspace" "dev" {
+  database_id = "f9f4b1e0-4c05-451e-9bba-d631295a7f73"
+  name        = "puppies"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/data-sources/keyspaces.md b/docs/data-sources/keyspaces.md
@@ -3,14 +3,20 @@
 page_title: "astra_keyspaces Data Source - terraform-provider-astra"
 subcategory: ""
 description: |-
-  Retrieve a list of keyspaces for an Astra database.
+  astra_keyspaces provides a datasource that lists the keyspaces in an Astra database.
 ---
 
 # astra_keyspaces (Data Source)
 
-Retrieve a list of keyspaces for an Astra database.
+`astra_keyspaces` provides a datasource that lists the keyspaces in an Astra database.
 
+## Example Usage
 
+```terraform
+data "astra_keyspaces" "dev" {
+  database_id = "f9f4b1e0-4c05-451e-9bba-d631295a7f73"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/data-sources/secure_connect_bundle_url.md b/docs/data-sources/secure_connect_bundle_url.md
@@ -3,14 +3,20 @@
 page_title: "astra_secure_connect_bundle_url Data Source - terraform-provider-astra"
 subcategory: ""
 description: |-
-  Generate a temporary secure connect bundle URL for an Astra database.
+  astra_secure_connect_bundle_url provides a datasource that generates a temporary secure connect bundle URL. This URL lasts five minutes. Secure connect bundles are used to connect to Astra using cql cassandra drivers. See the docs https://docs.datastax.com/en/astra/docs/connecting-to-database.html for more information on how to connect.
 ---
 
 # astra_secure_connect_bundle_url (Data Source)
 
-Generate a temporary secure connect bundle URL for an Astra database.
+`astra_secure_connect_bundle_url` provides a datasource that generates a temporary secure connect bundle URL. This URL lasts five minutes. Secure connect bundles are used to connect to Astra using cql cassandra drivers. See the [docs](https://docs.datastax.com/en/astra/docs/connecting-to-database.html) for more information on how to connect.
 
+## Example Usage
 
+```terraform
+data "astra_secure_connect_bundle_url" "dev" {
+  database_id = "f9f4b1e0-4c05-451e-9bba-d631295a7f73"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/index.md b/docs/index.md
@@ -1,18 +1,23 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "astra Provider"
-subcategory: ""
+layout: ""
+page_title: "Provider: DataStax Astra - Serverless Cassandra DBaaS"
 description: |-
-  
+  The Astra provider provides Terraform resources to interact with DataStax Astra databases.
 ---
 
-# astra Provider
+# DataStax Astra Provider
 
+  This provider allows DataStax Astra users to manage their full database lifecycle for Astra Serverless databases (built on Apache Cassandra(TM))
+  using Terraform.
 
+  To get started, log into [Astra](https://astra.datastax.com/register) and create an authorization token (in your organization settings). The provider will prompt you for the token
+  on apply if it does not detect it in your environment variable `ASTRA_API_TOKEN`.
+
+  Currently Astra Streaming (based on Apache Pulsar) is not supported.
 
 ## Example Usage
 
-```terraform
+  ```terraform
 variable "token" {}
 
 provider "astra" {
@@ -21,9 +26,8 @@ provider "astra" {
 }
 ```
 
-<!-- schema generated by tfplugindocs -->
-## Schema
+## Additional Info
 
-### Optional
+To report bugs or feature requests [file an issue on github](https://github.com/datastax/terraform-provider-astra/issues).
 
-- **token** (String) Authentication token for Astra API.
+For general help contact [support](https://houston.datastax.com/).
diff --git a/docs/resources/database.md b/docs/resources/database.md
@@ -3,12 +3,12 @@
 page_title: "astra_database Resource - terraform-provider-astra"
 subcategory: ""
 description: |-
-  Astra Database.
+  astra_database provides an Astra Serverless Database resource. You can create and delete databases. Note: Classic Tier databases are not supported by the Terraform provider.
 ---
 
 # astra_database (Resource)
 
-Astra Database.
+`astra_database` provides an Astra Serverless Database resource. You can create and delete databases. Note: Classic Tier databases are not supported by the Terraform provider.
 
 ## Example Usage
 

diff --git a/docs/resources/keyspace.md b/docs/resources/keyspace.md
@@ -3,12 +3,12 @@
 page_title: "astra_keyspace Resource - terraform-provider-astra"
 subcategory: ""
 description: |-
-  Astra database Keyspace.
+  astra_keyspace provides a keyspace resource. Keyspaces are groupings of tables for Cassandra. astra_keyspace resources are associated with a database id. You can have multiple keyspaces per DB in addition to the default keyspace provided in the astra_database resource.
 ---
 
 # astra_keyspace (Resource)
 
-Astra database Keyspace.
+`astra_keyspace` provides a keyspace resource. Keyspaces are groupings of tables for Cassandra. `astra_keyspace` resources are associated with a database id. You can have multiple keyspaces per DB in addition to the default keyspace provided in the `astra_database` resource.
 
 ## Example Usage
 

diff --git a/...tabase_with_keyspaces_and_scb/resource.tf → ...tabase_with_keyspaces_and_scb/resource.tf b/...tabase_with_keyspaces_and_scb/resource.tf → ...tabase_with_keyspaces_and_scb/resource.tf
diff --git a/...rom _existing_astra_databases/resource.tf → ...rom _existing_astra_databases/resource.tf b/...rom _existing_astra_databases/resource.tf → ...rom _existing_astra_databases/resource.tf
diff --git a/...data_source_available_regions/resource.tf → ...es/astra_available_regions/data-source.tf b/...data_source_available_regions/resource.tf → ...es/astra_available_regions/data-source.tf
diff --git a/examples/data-sources/astra_database/data-source.tf b/examples/data-sources/astra_database/data-source.tf
@@ -0,0 +1,3 @@
+data "astra_database" "db" {
+  database_id = "8d356587-73b3-430a-9c0e-d780332e2afb"
+}
diff --git a/.../resources/existing_databases/resource.tf → ...ta-sources/astra_databases/data-source.tf b/.../resources/existing_databases/resource.tf → ...ta-sources/astra_databases/data-source.tf
diff --git a/examples/data-sources/astra_keyspace/data-source.tf b/examples/data-sources/astra_keyspace/data-source.tf
@@ -0,0 +1,4 @@
+data "astra_keyspace" "dev" {
+  database_id = "f9f4b1e0-4c05-451e-9bba-d631295a7f73"
+  name        = "puppies"
+}
diff --git a/examples/data-sources/astra_keyspaces/data-source.tf b/examples/data-sources/astra_keyspaces/data-source.tf
@@ -0,0 +1,3 @@
+data "astra_keyspaces" "dev" {
+  database_id = "f9f4b1e0-4c05-451e-9bba-d631295a7f73"
+}
diff --git a/examples/data-sources/astra_secure_connect_bundle_url/data-source.tf b/examples/data-sources/astra_secure_connect_bundle_url/data-source.tf
@@ -0,0 +1,3 @@
+data "astra_secure_connect_bundle_url" "dev" {
+  database_id = "f9f4b1e0-4c05-451e-9bba-d631295a7f73"
+}
diff --git a/internal/provider/data_source_database.go b/internal/provider/data_source_database.go
@@ -12,7 +12,7 @@ import (
 
 func dataSourceDatabase() *schema.Resource {
 	return &schema.Resource{
-		Description: "Datasource for Astra database.",
+		Description: "`astra_database` provides a datasource for Astra an Astra database. This can be used to select an existing database within your Astra Organization.",
 
 		ReadContext: dataSourceDatabaseRead,
 

diff --git a/internal/provider/data_source_databases.go b/internal/provider/data_source_databases.go
@@ -11,7 +11,7 @@ import (
 
 func dataSourceDatabases() *schema.Resource {
 	return &schema.Resource{
-		Description: "Retrieve a list of Astra databases.",
+		Description: "`astra_databases` provides a datasource for a list of Astra databases. This can be used to select databases within your Astra Organization.",
 
 		ReadContext: dataSourceDatabasesRead,
 

diff --git a/internal/provider/data_source_keyspace.go b/internal/provider/data_source_keyspace.go
@@ -12,7 +12,7 @@ import (
 
 func dataSourceKeyspace() *schema.Resource {
 	return &schema.Resource{
-		Description: "Keyspace for an Astra database.",
+		Description: "`astra_keyspace` provides a datasource for a particular keyspace. See `astra_keyspaces` if you're looking to fetch all the keyspaces for a particular database.",
 
 		ReadContext: dataSourceKeyspaceRead,
 

diff --git a/internal/provider/data_source_keyspaces.go b/internal/provider/data_source_keyspaces.go
@@ -13,7 +13,7 @@ import (
 
 func dataSourceKeyspaces() *schema.Resource {
 	return &schema.Resource{
-		Description: "Retrieve a list of keyspaces for an Astra database.",
+		Description: "`astra_keyspaces` provides a datasource that lists the keyspaces in an Astra database.",
 
 		ReadContext: dataSourceKeyspacesRead,
 

diff --git a/internal/provider/data_source_secure_connect_bundle_url.go b/internal/provider/data_source_secure_connect_bundle_url.go
@@ -14,7 +14,7 @@ import (
 
 func dataSourceSecureConnectBundleURL() *schema.Resource {
 	return &schema.Resource{
-		Description: "Generate a temporary secure connect bundle URL for an Astra database.",
+		Description: "`astra_secure_connect_bundle_url` provides a datasource that generates a temporary secure connect bundle URL. This URL lasts five minutes. Secure connect bundles are used to connect to Astra using cql cassandra drivers. See the [docs](https://docs.datastax.com/en/astra/docs/connecting-to-database.html) for more information on how to connect.",
 
 		ReadContext: dataSourceSecureConnectBundleURLRead,
 

diff --git a/internal/provider/provider.go b/internal/provider/provider.go
@@ -36,7 +36,7 @@ func New(version string) func() *schema.Provider {
 				"astra_keyspace":                      dataSourceKeyspace(),
 				"astra_keyspaces":                     dataSourceKeyspaces(),
 				"astra_secure_connect_bundle_url":     dataSourceSecureConnectBundleURL(),
-				"astra_data_source_available_regions": dataSourceAvailableRegions(),
+				"astra_available_regions":			   dataSourceAvailableRegions(),
 			},
 			ResourcesMap: map[string]*schema.Resource{
 				"astra_database": resourceDatabase(),

diff --git a/internal/provider/resource_database.go b/internal/provider/resource_database.go
@@ -26,8 +26,7 @@ var databaseReadTimeout = time.Minute * 5
 
 func resourceDatabase() *schema.Resource {
 	return &schema.Resource{
-		Description: "Astra Database.",
-
+		Description: "`astra_database` provides an Astra Serverless Database resource. You can create and delete databases. Note: Classic Tier databases are not supported by the Terraform provider.",
 		CreateContext: resourceDatabaseCreate,
 		ReadContext:   resourceDatabaseRead,
 		DeleteContext: resourceDatabaseDelete,

diff --git a/internal/provider/resource_keyspace.go b/internal/provider/resource_keyspace.go
@@ -14,8 +14,7 @@ import (
 
 func resourceKeyspace() *schema.Resource {
 	return &schema.Resource{
-		Description: "Astra database Keyspace.",
-
+		Description: "`astra_keyspace` provides a keyspace resource. Keyspaces are groupings of tables for Cassandra. `astra_keyspace` resources are associated with a database id. You can have multiple keyspaces per DB in addition to the default keyspace provided in the `astra_database` resource.",
 		CreateContext: resourceKeyspaceCreate,
 		ReadContext:   resourceKeyspaceRead,
 		DeleteContext: resourceKeyspaceDelete,

diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
@@ -0,0 +1,26 @@
+---
+layout: ""
+page_title: "Provider: DataStax Astra - Serverless Cassandra DBaaS"
+description: |-
+  The Astra provider provides Terraform resources to interact with DataStax Astra databases.
+---
+
+# DataStax Astra Provider
+
+  This provider allows DataStax Astra users to manage their full database lifecycle for Astra Serverless databases (built on Apache Cassandra(TM))
+  using Terraform.
+
+  To get started, log into [Astra](https://astra.datastax.com/register) and create an authorization token (in your organization settings). The provider will prompt you for the token
+  on apply if it does not detect it in your environment variable `ASTRA_API_TOKEN`.
+
+  Currently Astra Streaming (based on Apache Pulsar) is not supported.
+
+## Example Usage
+
+  {{tffile "examples/provider/provider.tf"}}
+
+## Additional Info
+
+To report bugs or feature requests [file an issue on github](https://github.com/datastax/terraform-provider-astra/issues).
+
+For general help contact [support](https://houston.datastax.com/).