Tutorial 11: Generate documentation.

.copywrite.hcl

@@ -21,5 +21,8 @@ project {
 
     # GoReleaser tooling configuration
     ".goreleaser.yml",
+
+    # Configs
+    "terraformrc-*.tf",
   ]
 }

.gitignore

@@ -25,6 +25,7 @@ website/node_modules
 *.iml
 *.test
 *.iml
+docs/
 
 website/vendor
 

examples/data-sources/hashicups_coffees/data-source.tf

@@ -0,0 +1,2 @@
+# List all coffees.
+data "hashicups_coffees" "all" {}

examples/data-sources/scaffolding_example/data-source.tf

@@ -1,3 +0,0 @@
-data "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}

examples/functions/compute_tax/function.tf

@@ -0,0 +1,4 @@
+# Compute total price with tax
+output "total_price" {
+  value = provider::hashicups::compute_tax(5.00, 0.085)
+}

examples/provider/provider.tf

@@ -1,3 +1,6 @@
-provider "scaffolding" {
-  # example configuration here
+# Configuration-based authentication
+provider "hashicups" {
+  username = "education"
+  password = "test123"
+  host     = "http://localhost:19090"
 }

examples/resources/hashicups_order/import.sh

@@ -0,0 +1,2 @@
+# Order can be imported by specifying the numeric identifier.
+terraform import hashicups_order.example 123

examples/resources/hashicups_order/resource.tf

@@ -0,0 +1,11 @@
+# Manage example order.
+resource "hashicups_order" "example" {
+  items = [
+    {
+      coffee = {
+        id = 3
+      }
+      quantity = 2
+    },
+  ]
+}

examples/resources/scaffolding_example/resource.tf

@@ -1,3 +0,0 @@
-resource "scaffolding_example" "example" {
-  configurable_attribute = "some-value"
-}

internal/provider/coffees_data_source.go

@@ -65,29 +65,37 @@ func (d *coffeesDataSource) Schema(_ context.Context, _ datasource.SchemaRequest
 				NestedObject: schema.NestedAttributeObject{
 					Attributes: map[string]schema.Attribute{
 						"id": schema.Int64Attribute{
-							Computed: true,
+							Computed:    true,
+							Description: "Numeric identifier of the coffee.",
 						},
 						"name": schema.StringAttribute{
-							Computed: true,
+							Computed:    true,
+							Description: "Product name of the coffee.",
 						},
 						"teaser": schema.StringAttribute{
-							Computed: true,
+							Computed:    true,
+							Description: "Fun tagline for the coffee.",
 						},
 						"description": schema.StringAttribute{
-							Computed: true,
+							Computed:    true,
+							Description: "Product description of the coffee.",
 						},
 						"price": schema.Float64Attribute{
-							Computed: true,
+							Computed:    true,
+							Description: "Suggested cost of the coffee.",
 						},
 						"image": schema.StringAttribute{
-							Computed: true,
+							Computed:    true,
+							Description: "URI for an image of the coffee.",
 						},
 						"ingredients": schema.ListNestedAttribute{
-							Computed: true,
+							Computed:    true,
+							Description: "List of ingredients in the coffee.",
 							NestedObject: schema.NestedAttributeObject{
 								Attributes: map[string]schema.Attribute{
 									"id": schema.Int64Attribute{
-										Computed: true,
+										Description: "Numeric identifier of the coffee ingredient.",
+										Computed:    true,
 									},
 								},
 							},

internal/provider/coffees_data_source_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
 package provider
 
 import (

internal/provider/compute_tax_function.go

@@ -1,3 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
 package provider
 
 import (

internal/provider/compute_tax_function_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
 package provider
 
 import (

internal/provider/order_resource.go

@@ -1,3 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
 package provider
 
 import (
@@ -67,41 +70,51 @@ func (r *orderResource) Schema(_ context.Context, _ resource.SchemaRequest, resp
 	resp.Schema = schema.Schema{
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
-				Computed: true,
+				Computed:    true,
+				Description: "Numeric identifier of the order.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.UseStateForUnknown(),
 				},
 			},
 			"last_updated": schema.StringAttribute{
-				Computed: true,
+				Computed:    true,
+				Description: "Timestamp of the last Terraform update of the order.",
 			},
 			"items": schema.ListNestedAttribute{
-				Required: true,
+				Description: "List of items in the order.",
+				Required:    true,
 				NestedObject: schema.NestedAttributeObject{
 					Attributes: map[string]schema.Attribute{
 						"quantity": schema.Int64Attribute{
-							Required: true,
+							Description: "Count of this item in the order.",
+							Required:    true,
 						},
 						"coffee": schema.SingleNestedAttribute{
 							Required: true,
 							Attributes: map[string]schema.Attribute{
 								"id": schema.Int64Attribute{
-									Required: true,
+									Description: "Numeric identifier of the coffee.",
+									Required:    true,
 								},
 								"name": schema.StringAttribute{
-									Computed: true,
+									Computed:    true,
+									Description: "Product name of the coffee.",
 								},
 								"teaser": schema.StringAttribute{
-									Computed: true,
+									Computed:    true,
+									Description: "Fun tagline for the coffee.",
 								},
 								"description": schema.StringAttribute{
-									Computed: true,
+									Computed:    true,
+									Description: "Product description of the coffee.",
 								},
 								"price": schema.Float64Attribute{
-									Computed: true,
+									Computed:    true,
+									Description: "Suggested cost of the coffee.",
 								},
 								"image": schema.StringAttribute{
-									Computed: true,
+									Computed:    true,
+									Description: "URI for an image of the coffee.",
 								},
 							},
 						},

internal/provider/order_resource_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
 package provider
 
 import (

internal/provider/provider.go

@@ -1,3 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
 package provider
 
 import (
@@ -58,14 +61,17 @@ func (p *hashicupsProvider) Schema(_ context.Context, _ provider.SchemaRequest,
 	resp.Schema = schema.Schema{
 		Attributes: map[string]schema.Attribute{
 			"host": schema.StringAttribute{
-				Optional: true,
+				Description: "URI for HashiCups API. May also be provided via HASHICUPS_HOST environment variable.",
+				Optional:    true,
 			},
 			"username": schema.StringAttribute{
-				Optional: true,
+				Description: "Username for HashiCups API. May also be provided via HASHICUPS_USERNAME environment variable.",
+				Optional:    true,
 			},
 			"password": schema.StringAttribute{
-				Optional:  true,
-				Sensitive: true,
+				Description: "Password for HashiCups API. May also be provided via HASHICUPS_PASSWORD environment variable.",
+				Optional:    true,
+				Sensitive:   true,
 			},
 		},
 	}

internal/provider/provider_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) HashiCorp, Inc.
+// SPDX-License-Identifier: MPL-2.0
+
 package provider
 
 import (