Merge pull request #33022 from hashicorp/d-content-tabs-proto

[Docs]: Config and example content for content tabs
hashicorp · Sep 19, 2023 · f9e7daa · f9e7daa
2 parents d980293 + 9aadc03
commit f9e7daa
Show file tree

Hide file tree

Showing 3 changed files with 110 additions and 54 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -1,4 +1,21 @@
 # Documentation
 
-- [Using the AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
-- [AWS Provider contributing guide](https://hashicorp.github.io/terraform-provider-aws/)
+This directory contains documentation for the [Terraform AWS Provider Contributor Guide](https://hashicorp.github.io/terraform-provider-aws/). Resource and data source documentation is located in the [`website`](../website/) directory and available in the [Terraform Registry](https://registry.terraform.io/providers/hashicorp/aws/latest/docs).
+
+## Local Development
+
+To serve the contributing guide locally, [`mkdocs`](https://www.mkdocs.org/user-guide/installation/) and the [`mkdocs-material`](https://github.com/squidfunk/mkdocs-material#quick-start) extension must be installed. Both require Python and `pip`.
+
+```console
+% pip3 install mkdocs
+```
+
+```console
+% pip3 install mkdocs-material
+```
+
+Once installed, the documentation can be served from the root directory:
+
+```console
+% mkdocs serve
+```
diff --git a/docs/add-a-new-service.md b/docs/add-a-new-service.md
@@ -51,62 +51,98 @@ If an AWS service must be created in a non-standard way, for example the service
 
 1. Add a file `internal/<service>/service_package.go` that contains an API client factory function, for example:
 
-```go
-package globalaccelerator
-
-import (
-	"context"
-
-	aws_sdkv1 "github.com/aws/aws-sdk-go/aws"
-	endpoints_sdkv1 "github.com/aws/aws-sdk-go/aws/endpoints"
-	session_sdkv1 "github.com/aws/aws-sdk-go/aws/session"
-	globalaccelerator_sdkv1 "github.com/aws/aws-sdk-go/service/globalaccelerator"
-)
-
-// NewConn returns a new AWS SDK for Go v1 client for this service package's AWS API.
-func (p *servicePackage) NewConn(ctx context.Context) (*globalaccelerator_sdkv1.GlobalAccelerator, error) {
-	sess := p.config["session"].(*session_sdkv1.Session)
-	config := &aws_sdkv1.Config{Endpoint: aws_sdkv1.String(p.config["endpoint"].(string))}
-
-	// Force "global" services to correct Regions.
-	if p.config["partition"].(string) == endpoints_sdkv1.AwsPartitionID {
-		config.Region = aws_sdkv1.String(endpoints_sdkv1.UsWest2RegionID)
-	}
-
-	return globalaccelerator_sdkv1.New(sess.Copy(config)), nil
-}
-```
+<!-- markdownlint-disable code-block-style -->
+=== "aws-go-sdk-v2"
+
+    ```go
+    package route53domains
+
+    import (
+    	"context"
+
+    	aws_sdkv2 "github.com/aws/aws-sdk-go-v2/aws"
+    	route53domains_sdkv2 "github.com/aws/aws-sdk-go-v2/service/route53domains"
+    	endpoints_sdkv1 "github.com/aws/aws-sdk-go/aws/endpoints"
+    )
+
+    // NewClient returns a new AWS SDK for Go v2 client for this service package's AWS API.
+    func (p *servicePackage) NewClient(ctx context.Context, config map[string]any) (*route53domains_sdkv2.Client, error) {
+    	cfg := *(config["aws_sdkv2_config"].(*aws_sdkv2.Config))
+
+    	return route53domains_sdkv2.NewFromConfig(cfg, func(o *route53domains_sdkv2.Options) {
+    		if endpoint := config["endpoint"].(string); endpoint != "" {
+    			o.BaseEndpoint = aws_sdkv2.String(endpoint)
+    		} else if config["partition"].(string) == endpoints_sdkv1.AwsPartitionID {
+    			// Route 53 Domains is only available in AWS Commercial us-east-1 Region.
+    			o.Region = endpoints_sdkv1.UsEast1RegionID
+    		}
+    	}), nil
+    }
+    ```
+
+=== "aws-go-sdk"
+
+    ```go
+    package globalaccelerator
+
+    import (
+        "context"
+
+        aws_sdkv1 "github.com/aws/aws-sdk-go/aws"
+        endpoints_sdkv1 "github.com/aws/aws-sdk-go/aws/endpoints"
+        session_sdkv1 "github.com/aws/aws-sdk-go/aws/session"
+        globalaccelerator_sdkv1 "github.com/aws/aws-sdk-go/service/globalaccelerator"
+    )
+
+    // NewConn returns a new AWS SDK for Go v1 client for this service package's AWS API.
+    func (p *servicePackage) NewConn(ctx context.Context) (*globalaccelerator_sdkv1.GlobalAccelerator, error) {
+        sess := p.config["session"].(*session_sdkv1.Session)
+        config := &aws_sdkv1.Config{Endpoint: aws_sdkv1.String(p.config["endpoint"].(string))}
+
+        // Force "global" services to correct Regions.
+        if p.config["partition"].(string) == endpoints_sdkv1.AwsPartitionID {
+            config.Region = aws_sdkv1.String(endpoints_sdkv1.UsWest2RegionID)
+        }
+
+        return globalaccelerator_sdkv1.New(sess.Copy(config)), nil
+    }
+    ```
+<!-- markdownlint-enable code-block-style -->
 
 ## Customizing a new Service Client
 
 If an AWS service must be customized after creation, for example retry handling must be changed, then:
 
 1. Add a file `internal/<service>/service_package.go` that contains an API client customization function, for example:
 
-```go
-package chime
-
-import (
-	"context"
-
-	aws_sdkv1 "github.com/aws/aws-sdk-go/aws"
-	request_sdkv1 "github.com/aws/aws-sdk-go/aws/request"
-	chime_sdkv1 "github.com/aws/aws-sdk-go/service/chime"
-	"github.com/hashicorp/aws-sdk-go-base/v2/awsv1shim/v2/tfawserr"
-)
-
-// CustomizeConn customizes a new AWS SDK for Go v1 client for this service package's AWS API.
-func (p *servicePackage) CustomizeConn(ctx context.Context, conn *chime_sdkv1.Chime) (*chime_sdkv1.Chime, error) {
-	conn.Handlers.Retry.PushBack(func(r *request_sdkv1.Request) {
-		// When calling CreateVoiceConnector across multiple resources,
-		// the API can randomly return a BadRequestException without explanation
-		if r.Operation.Name == "CreateVoiceConnector" {
-			if tfawserr.ErrMessageContains(r.Error, chime_sdkv1.ErrCodeBadRequestException, "Service received a bad request") {
-				r.Retryable = aws_sdkv1.Bool(true)
-			}
-		}
-	})
-
-	return conn, nil
-}
-```
+<!-- markdownlint-disable code-block-style -->
+=== "aws-go-sdk"
+
+    ```go
+    package chime
+
+    import (
+    	"context"
+
+    	aws_sdkv1 "github.com/aws/aws-sdk-go/aws"
+    	request_sdkv1 "github.com/aws/aws-sdk-go/aws/request"
+    	chime_sdkv1 "github.com/aws/aws-sdk-go/service/chime"
+    	"github.com/hashicorp/aws-sdk-go-base/v2/awsv1shim/v2/tfawserr"
+    )
+
+    // CustomizeConn customizes a new AWS SDK for Go v1 client for this service package's AWS API.
+    func (p *servicePackage) CustomizeConn(ctx context.Context, conn *chime_sdkv1.Chime) (*chime_sdkv1.Chime, error) {
+    	conn.Handlers.Retry.PushBack(func(r *request_sdkv1.Request) {
+    		// When calling CreateVoiceConnector across multiple resources,
+    		// the API can randomly return a BadRequestException without explanation
+    		if r.Operation.Name == "CreateVoiceConnector" {
+    			if tfawserr.ErrMessageContains(r.Error, chime_sdkv1.ErrCodeBadRequestException, "Service received a bad request") {
+    				r.Retryable = aws_sdkv1.Bool(true)
+    			}
+    		}
+    	})
+
+    	return conn, nil
+    }
+    ```
+<!-- markdownlint-enable code-block-style -->
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -58,6 +58,7 @@ theme:
   features:
     - navigation.instant
     - content.tabs.link
+    - content.code.copy
 
 plugins:
   - search:
@@ -67,6 +68,8 @@ plugins:
 markdown_extensions:
   - pymdownx.highlight
   - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.inlinehilite
   - toc:
       permalink: "#"