From 042eb55cb3191282e8ffbae2cd05474eee609845 Mon Sep 17 00:00:00 2001 From: Austin Valle Date: Fri, 12 Jan 2024 17:44:58 -0500 Subject: [PATCH] Document the default behavior of `--tf-version` and usage of Terraform binary (#324) * Document the default behavior of `--tf-version` and usage of binary * add mention of `--providers-schema` and recommendation --- README.md | 12 ++++++++++-- internal/cmd/generate.go | 2 +- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4a4ffb72..b9cbb287 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ Usage: tfplugindocs generate [] --providers-schema 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 provider name, as generated in documentation (ex. page titles, ...) --rendered-website-dir output directory based on provider-dir (default: "docs") - --tf-version terraform binary version to download + --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 --website-source-dir templates directory based on provider-dir (default: "templates") --website-temp-dir 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 diff --git a/internal/cmd/generate.go b/internal/cmd/generate.go index a62907a1..1a0c7f15 100644 --- a/internal/cmd/generate.go +++ b/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 }