Document the default behavior of --tf-version and usage of Terrafor…

…m binary (#324)

* Document the default behavior of `--tf-version` and usage of binary

* add mention of `--providers-schema` and recommendation

README.md

@@ -70,7 +70,7 @@ Usage: tfplugindocs generate [<args>]
     --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                                                                                             
+    --tf-version <ARG>               terraform binary version to download. If not provided, will look for a terraform binary in the local environment. If not found in the environment, will download the latest version of Terraform                                                                                             
     --website-source-dir <ARG>       templates directory based on provider-dir                                                                                          (default: "templates")
     --website-temp-dir <ARG>         temporary directory (used during generation)  
 ```
@@ -115,6 +115,14 @@ You can browse their respective docs on the Terraform Registry,
 [here](https://registry.terraform.io/providers/hashicorp/random/latest/docs)
 and [here](https://registry.terraform.io/providers/hashicorp/tls/latest/docs).
 
+### Usage of Terraform binary
+
+If the `--providers-schema` flag is not provided, `tfplugindocs` will use the [Terraform binary](https://github.com/hashicorp/terraform) to generate the provider schema with the commands:
+- [`terraform init`](https://developer.hashicorp.com/terraform/cli/commands/init)
+- [`terraform providers schema`](https://developer.hashicorp.com/terraform/cli/commands/providers/schema)
+
+We recommend using the latest version of Terraform when using `tfplugindocs`, however, the version can be specified with the `--tf-version` flag if needed.
+
 #### About the `id` attribute
 
 If the provider schema didn't set `id` for the given resource/data-source, the documentation generated
@@ -263,7 +271,7 @@ using the following data fields and functions:
 | `tffile`        | A special case of the `codefile` function, designed for Terraform files (i.e. `.tf`).             |
 | `trimspace`     | Equivalent to [`strings.TrimSpace`](https://pkg.go.dev/strings#TrimSpace).                        |
 | `upper`         | Equivalent to [`strings.ToUpper`](https://pkg.go.dev/strings#ToUpper).                            |
- 
+
 ## Disclaimer
 
 This is still under development: while it's being used for production-ready providers, you might still find bugs

internal/cmd/generate.go

@@ -80,7 +80,7 @@ func (cmd *generateCmd) Flags() *flag.FlagSet {
 	fs.StringVar(&cmd.flagExamplesDir, "examples-dir", "examples", "examples directory based on provider-dir")
 	fs.StringVar(&cmd.flagWebsiteTmpDir, "website-temp-dir", "", "temporary directory (used during generation)")
 	fs.StringVar(&cmd.flagWebsiteSourceDir, "website-source-dir", "templates", "templates directory based on provider-dir")
-	fs.StringVar(&cmd.tfVersion, "tf-version", "", "terraform binary version to download")
+	fs.StringVar(&cmd.tfVersion, "tf-version", "", "terraform binary version to download. If not provided, will look for a terraform binary in the local environment. If not found in the environment, will download the latest version of Terraform")
 	fs.BoolVar(&cmd.flagIgnoreDeprecated, "ignore-deprecated", false, "don't generate documentation for deprecated resources and data-sources")
 	return fs
 }