Add support for --provider-schema flag and context to generate sub-command errors

.changes/unreleased/ENHANCEMENTS-20231117-151029.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'generate: Add `provider-schema` flag to pass in a file path to a provider schema JSON
+ file, allowing the command to skip building the provider and calling Terraform CLI'
+time: 2023-11-17T15:10:29.850914-05:00
+custom:
+ Issue: "299"

README.md

@@ -43,6 +43,7 @@ Usage: tfplugindocs generate [<args>]
  --ignore-deprecated <ARG> don't generate documentation for deprecated resources and data-sources (default: "false")
  --provider-dir <ARG> relative or absolute path to the root provider code directory when running the command outside the root provider code directory 
  --provider-name <ARG> provider name, as used in Terraform configurations 
+ --providers-schema <ARG> path to the providers schema JSON file, which contains the output of the terraform providers schema -json command. Setting this flag will skip building the provider and calling Terraform CLI 
  --rendered-provider-name <ARG> provider name, as generated in documentation (ex. page titles, ...) 
  --rendered-website-dir <ARG> output directory based on provider-dir (default: "docs")
  --tf-version <ARG> terraform binary version to download 
@@ -198,9 +199,15 @@ This can be autogenerated by running `make generate` or running `go generate ./.
 
 This repo uses the `testscript` [package](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript) for acceptance testing.
 
-You can run `make testacc` to run the acceptance tests. By default, the acceptance tests will create a temporary directory in `/tmp/tftmp` for testing but you can change this location in `cmd/tfplugindocs/main_test.go`
+There are two types of acceptance tests: full provider build tests in `tfplugindocs/testdata/scripts/provider-build` and provider schema json tests in `tfplugindocs/testdata/scripts/schema-json`.
 
-The test scripts are defined in the `tfplugindocs/testdata/scripts` directory. Each script includes the test, golden files, and the provider source code needed to run the test.
+Provider build tests run the default `tfplugindocs` command which builds the provider source code and runs Terraform to retrieve the schema. These tests require the full provider source code to build a valid provider binary. 
+
+Schema json tests run the `tfplugindocs` command with the `--providers-schema=<arg>` flag to specify a provider schemas json file. This allows the test to skip the provider build and Terraform CLI call, instead using the specified file to generate docs. 
+
+You can run `make testacc` to run the full suite of acceptance tests. By default, the provider build acceptance tests will create a temporary directory in `/tmp/tftmp` for testing, but you can change this location in `cmd/tfplugindocs/main_test.go`. The schema json tests uses the `testscript` package's [default work directory](https://pkg.go.dev/github.com/rogpeppe/go-internal/testscript#Params.WorkdirRoot).
+
+The test scripts are defined in the `tfplugindocs/testdata/scripts` directory. Each script includes the test, golden files, and the provider source code or schema JSON file needed to run the test.
 
 Each script is a [text archive](https://pkg.go.dev/golang.org/x/tools/txtar). You can install the `txtar` CLI locally by running `go install golang.org/x/exp/cmd/txtar@latest` to extract the files in the test script for debugging. 
 You can also use `txtar` CLI archive files into the `.txtar` format to create new tests or modify existing ones.

cmd/tfplugindocs/main_test.go

@@ -18,10 +18,10 @@ func TestMain(m *testing.M) {
  }))
 }
 
-func Test_GenerateAcceptanceTests(t *testing.T) {
+func Test_ProviderBuild_GenerateAcceptanceTests(t *testing.T) {
  t.Parallel()
  if os.Getenv("ACCTEST") == "" {
- t.Skip("ACCTEST env var not set; skipping acceptance tests.")
+ t.Skip("ACCTEST env var not set; skipping provider build acceptance tests.")
  }
  // Setting a custom temp dir instead of relying on os.TempDir()
  // because Terraform providers fail to start up when $TMPDIR
@@ -34,7 +34,15 @@ func Test_GenerateAcceptanceTests(t *testing.T) {
  defer os.RemoveAll(tmpDir)
 
  testscript.Run(t, testscript.Params{
- Dir: "testdata/scripts/generate",
+ Dir: "testdata/scripts/provider-build/generate",
  WorkdirRoot: tmpDir,
  })
 }
+
+func Test_SchemaJson_GenerateAcceptanceTests(t *testing.T) {
+ t.Parallel()
+
+ testscript.Run(t, testscript.Params{
+ Dir: "testdata/scripts/schema-json/generate",
+ })
+}