Update aws.s3.Bucket notes to point to aws.s3.BucketV2 (#4491)

Add a note for the aws.s3.Bucket page to direct users to
aws.s3.BucketV2.

Fixes pulumi/home#3629

Fix an issue with documentation override: due to a bug
`docs/resource/aws_s3_bucket_legacy.md` was not being picked up and the
`aws.s3.Bucket` page was incorrectly serving docs for the
`aws.s3.BucketV2` resource. This is fixed here.

This PR should not merge until
pulumi/registry#5444 gets published.

docs/resource/aws_s3_bucket_legacy.md

@@ -6,13 +6,14 @@ description: |-
 Provides a S3 bucket resource.
 ---
 
-# Resource: aws_s3_bucket
+# Resource: aws.s3.Bucket
 
 Provides a S3 bucket resource.
 
--> This functionality is for managing S3 in an AWS Partition. To manage [S3 on Outposts](https://docs.aws.amazon.com/AmazonS3/latest/dev/S3onOutposts.html), see the `aws_s3control_bucket` resource.
-
--> **NOTE:** This resource might not work well if using an alternative s3-compatible provider. Please use `aws.s3.BucketV2` instead.
+-> **NOTE:** Please use [aws.s3.BucketV2](https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketv2) instead.
+This resource is maintained for backwards compatibility only. Please see [BucketV2 Migration
+Guide](https://www.pulumi.com/registry/packages/aws/how-to-guides/bucketv2-migration/) for instructions on migrating
+existing Bucket resources to BucketV2.
 
 ## Example Usage
 

provider/doc_edits.go

@@ -250,3 +250,13 @@ func findLine(src []byte, i int) (int, int) {
 	}
 	return start, end + 1
 }
+
+// Attempts to read the contents of a given file but returns an empty array in case of failure. This is useful for
+// overriding documentation files at generation time only.
+func maybeReadFile(filePath string) []byte {
+	fileBytes, err := os.ReadFile(filePath)
+	if err != nil {
+		return nil
+	}
+	return fileBytes
+}

provider/resources.go

@@ -3756,7 +3756,7 @@ compatibility shim in favor of the new "name" field.`)
 						Transform: tfbridge.TransformJSONDocument,
 					},
 				},
-				Docs: &tfbridge.DocInfo{Source: "../../../../docs/resource/aws_s3_bucket_legacy.md"},
+				Docs: &tfbridge.DocInfo{Markdown: maybeReadFile("docs/resource/aws_s3_bucket_legacy.md")},
 			},
 			"aws_s3_bucket_inventory":    {Tok: awsResource(s3Mod, "Inventory")},
 			"aws_s3_bucket_metric":       {Tok: awsResource(s3Mod, "BucketMetric")},