Add provider installation docs and automation (#465)

This PR automates docsgen for this provider's installation doc.

Part of pulumi/home#3598.

- **Add docs automation**
- **Add a find/replace so we can translate the example**

.ci-mgmt.yaml

@@ -8,6 +8,7 @@ env:
 makeTemplate: bridged
 team: ecosystem
 pulumiConvert: 1
+registryDocs: true
 plugins:
   - name: terraform
     version: "1.0.16"

Makefile

@@ -29,7 +29,7 @@ development: install_plugins provider build_sdks install_sdks
 
 build: install_plugins provider build_sdks install_sdks
 
-build_sdks: build_nodejs build_python build_dotnet build_go build_java 
+build_sdks: build_nodejs build_python build_dotnet build_go build_java build_registry_docs
 
 install_go_sdk:
 
@@ -96,6 +96,10 @@ build_python: upstream
 		cd ./bin && \
 		../venv/bin/python -m build .
 
+# Run the bridge's registry-docs command to generated the content of the installation docs/ folder at provider repo root
+build_registry_docs:
+	$(WORKING_DIR)/bin/$(TFGEN) registry-docs --out $(WORKING_DIR)/docs
+
 clean:
 	rm -rf sdk/{dotnet,nodejs,go,python}
 

docs/_index.md

@@ -0,0 +1,143 @@
+---
+title: Splunk Provider
+meta_desc: Provides an overview on how to configure the Pulumi Splunk provider.
+layout: package
+---
+## Installation
+
+The splunk provider is available as a package in all Pulumi languages:
+
+* JavaScript/TypeScript: [`@pulumi/splunk`](https://www.npmjs.com/package/@pulumi/splunk)
+* Python: [`pulumi-splunk`](https://pypi.org/project/pulumi-splunk/)
+* Go: [`github.com/pulumi/pulumi-splunk/sdk/go/splunk`](https://github.com/pulumi/pulumi-splunk)
+* .NET: [`Pulumi.Splunk`](https://www.nuget.org/packages/Pulumi.Splunk)
+* Java: [`com.pulumi/splunk`](https://central.sonatype.com/artifact/com.pulumi/splunk)
+## Overview
+
+The Splunk provider can interact with the resources supported by Splunk. The provider needs to be configured with the proper credentials before it can be used.
+## Example Usage
+
+{{< chooser language "typescript,python,go,csharp,java,yaml" >}}
+{{% choosable language typescript %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: nodejs
+config:
+    splunk:insecureSkipVerify:
+        value: true
+    splunk:password:
+        value: changeme
+    splunk:url:
+        value: localhost:8089
+    splunk:username:
+        value: admin
+
+```
+
+{{% /choosable %}}
+{{% choosable language python %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: python
+config:
+    splunk:insecureSkipVerify:
+        value: true
+    splunk:password:
+        value: changeme
+    splunk:url:
+        value: localhost:8089
+    splunk:username:
+        value: admin
+
+```
+
+{{% /choosable %}}
+{{% choosable language csharp %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: dotnet
+config:
+    splunk:insecureSkipVerify:
+        value: true
+    splunk:password:
+        value: changeme
+    splunk:url:
+        value: localhost:8089
+    splunk:username:
+        value: admin
+
+```
+
+{{% /choosable %}}
+{{% choosable language go %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: go
+config:
+    splunk:insecureSkipVerify:
+        value: true
+    splunk:password:
+        value: changeme
+    splunk:url:
+        value: localhost:8089
+    splunk:username:
+        value: admin
+
+```
+
+{{% /choosable %}}
+{{% choosable language yaml %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: yaml
+config:
+    splunk:insecureSkipVerify:
+        value: true
+    splunk:password:
+        value: changeme
+    splunk:url:
+        value: localhost:8089
+    splunk:username:
+        value: admin
+
+```
+
+{{% /choosable %}}
+{{% choosable language java %}}
+```yaml
+# Pulumi.yaml provider configuration file
+name: configuration-example
+runtime: java
+config:
+    splunk:insecureSkipVerify:
+        value: true
+    splunk:password:
+        value: changeme
+    splunk:url:
+        value: localhost:8089
+    splunk:username:
+        value: admin
+
+```
+
+{{% /choosable %}}
+{{< /chooser >}}
+## Configuration Reference
+
+Below arguments for the provider can also be set as environment variables.
+
+* `url` or `SPLUNK_URL` - (Required) The URL for the Splunk instance to be configured. (The provider uses `https` as the default schema as prefix to the URL)
+* `username` or `SPLUNK_USERNAME`  - (Optional) The username to access the Splunk instance to be configured.
+* `password` or `SPLUNK_PASSWORD` - (Optional) The password to access the Splunk instance to be configured.
+* `authToken` or `SPLUNK_AUTH_TOKEN` - (Optional) Use auth token instead of username and password to configure Splunk instance.
+  If specified, auth token takes priority over username/password.
+* `insecureSkipVerify` or `SPLUNK_INSECURE_SKIP_VERIFY` - (Optional) Insecure skip verification flag (Defaults to `true`)
+* `timeout` or `SPLUNK_TIMEOUT` -  (Optional) Timeout when making calls to Splunk server. (Defaults to `60 seconds`)
+
+(NOTE: Auth token can only be used with certain type of Splunk deployments.
+Read more on authentication with tokens here: <https://docs.splunk.com/Documentation/Splunk/latest/Security/Setupauthenticationwithtokens>)

docs/index-md-replaces/examples-desired.md

@@ -0,0 +1,10 @@
+## Example Usage
+
+```terraform
+provider "splunk" {
+  url                  = "localhost:8089"
+  username             = "admin"
+  password             = "changeme"
+  insecure_skip_verify = true
+}
+```

docs/index-md-replaces/examples-input.md

@@ -0,0 +1,21 @@
+## Example Usage
+
+```
+provider "splunk" {
+  url                  = "localhost:8089"
+  username             = "admin"
+  password             = "changeme"
+  insecure_skip_verify = true
+}
+```
+
+Terraform 0.13 and later must add:
+```
+terraform {
+   required_providers {
+    splunk = {
+      source  = "splunk/splunk"
+    }
+  }
+}
+```

provider/resources.go

@@ -15,7 +15,9 @@
 package splunk
 
 import (
+	"bytes"
 	"fmt"
+	"os"
 	"path/filepath"
 	"unicode"
 
@@ -77,6 +79,7 @@ func Provider() tfbridge.ProviderInfo {
 		Repository:  "https://github.com/pulumi/pulumi-splunk",
 		GitHubOrg:   "splunk",
 		Config:      map[string]*tfbridge.SchemaInfo{},
+		DocRules:    &tfbridge.DocRuleInfo{EditRules: docEditRules},
 		Resources: map[string]*tfbridge.ResourceInfo{
 			"splunk_admin_saml_groups": {
 				Tok: makeResource(mainMod, "AdminSamlGroups"),
@@ -246,3 +249,36 @@ func Provider() tfbridge.ProviderInfo {
 
 	return prov
 }
+func docEditRules(defaults []tfbridge.DocsEdit) []tfbridge.DocsEdit {
+	return append(
+		defaults,
+		cleanUpExample,
+	)
+}
+
+var cleanUpExample = tfbridge.DocsEdit{
+	Path: "index.md",
+	Edit: func(_ string, content []byte) ([]byte, error) {
+		replacesDir := "docs/index-md-replaces/"
+
+		input, err := os.ReadFile(replacesDir + "examples-input.md")
+		if err != nil {
+			return nil, err
+		}
+		desired, err := os.ReadFile(replacesDir + "examples-desired.md")
+		if err != nil {
+			return nil, err
+		}
+		if bytes.Contains(content, input) {
+			content = bytes.ReplaceAll(
+				content,
+				input,
+				desired)
+		} else {
+			// Hard error to ensure we keep this content up to date
+			return nil, fmt.Errorf("could not find text in upstream index.md, "+
+				"please verify file content at %s\n*****\n%s\n*****\n", replacesDir+"overview-input.md", string(input))
+		}
+		return content, nil
+	},
+}