generate: Introduce provider-dir flag (#259)

Reference: #13

By default, the generator expects to be running in the root provider directory. The new `provider-dir` flag enables developers to run the command in any directory where the relative or absolute path is passed in as the base directory for all file operations for a provider codebase. All prior behaviors should be preserved, such as customizing via other flags like `examples-dir`.

Due to lack of existing end-to-end testing (known technical debt), verified by locally compiling and running against existing HashiCorp-owned provider implementations which use `tfplugindocs` and by running the command in a subdirectory of hashicorp/terraform-provider-tls which has a mixture of custom and default templates and observed no changes or errors:

```console
$ tfplugindocs generate -provider-dir=..
rendering website for provider "terraform-provider-tls" (as "terraform-provider-tls")
copying any existing content to tmp dir
exporting schema from Terraform
compiling provider "tls"
using Terraform CLI binary from PATH if available, otherwise downloading latest Terraform CLI binary
running terraform init
getting provider schema
rendering missing docs
generating missing resource content
resource "tls_locally_signed_cert" template exists, skipping
resource "tls_private_key" template exists, skipping
resource "tls_self_signed_cert" template exists, skipping
resource "tls_cert_request" template exists, skipping
generating missing data source content
resource "tls_certificate" template exists, skipping
generating template for "tls_public_key"
generating missing provider content
provider "terraform-provider-tls" template exists, skipping
rendering static website
cleaning rendered website dir
rendering templated website to static markdown
rendering "data-sources/certificate.md.tmpl"
rendering "data-sources/public_key.md.tmpl"
rendering "index.md.tmpl"
rendering "resources/cert_request.md.tmpl"
rendering "resources/locally_signed_cert.md.tmpl"
rendering "resources/private_key.md.tmpl"
rendering "resources/self_signed_cert.md.tmpl"
```

Author: bflad

.changes/unreleased/ENHANCEMENTS-20230606-141357.yaml

@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'generate: Added `provider-dir` flag, which enables the command to be run from
+  any directory'
+time: 2023-06-06T14:13:57.482032-04:00
+custom:
+  Issue: "259"

README.md

@@ -27,7 +27,7 @@ Usage: tfplugindocs [--version] [--help] <command> [<args>]
 
 Available commands are:
                 the generate command is run by default
-    generate    generates a plugin website from code, templates, and examples for the current directory
+    generate    generates a plugin website from code, templates, and examples
     validate    validates a plugin website for the current directory
 
 ```
@@ -39,14 +39,15 @@ $ tfplugindocs generate --help
 
 Usage: tfplugindocs generate [<args>]
 
-    --examples-dir <ARG>             examples directory                                                        (default: "examples")
-    --ignore-deprecated <ARG>        don't generate documentation for deprecated resources and data-sources    (default: "false")
-    --provider-name <ARG>            provider name, as used in Terraform configurations
-    --rendered-provider-name <ARG>   provider name, as generated in documentation (ex. page titles, ...)
-    --rendered-website-dir <ARG>     output directory                                                          (default: "docs")
-    --tf-version <ARG>               terraform binary version to download
-    --website-source-dir <ARG>       templates directory                                                       (default: "templates")
-    --website-temp-dir <ARG>         temporary directory (used during generation)
+    --examples-dir <ARG>             examples directory based on provider-dir                                                                                           (default: "examples")
+    --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                                                                               
+    --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                                                                                             
+    --website-source-dir <ARG>       templates directory based on provider-dir                                                                                          (default: "templates")
+    --website-temp-dir <ARG>         temporary directory (used during generation)  
 ```
 
 `validate` command:
@@ -59,7 +60,7 @@ Usage: tfplugindocs validate [<args>]
 
 ### How it Works
 
-When you run `tfplugindocs` from root directory of the provider the tool takes the following actions:
+When you run `tfplugindocs`, by default from the root directory of a provider codebase, the tool takes the following actions:
 
 * Copy all the templates and static files to a temporary directory
 * Build (`go build`) a temporary binary of the provider source code

internal/cmd/generate.go

@@ -19,6 +19,7 @@ type generateCmd struct {
 	flagProviderName         string
 	flagRenderedProviderName string
 
+	flagProviderDir        string
 	flagRenderedWebsiteDir string
 	flagExamplesDir        string
 	flagWebsiteTmpDir      string
@@ -27,7 +28,7 @@ type generateCmd struct {
 }
 
 func (cmd *generateCmd) Synopsis() string {
-	return "generates a plugin website from code, templates, and examples for the current directory"
+	return "generates a plugin website from code, templates, and examples"
 }
 
 func (cmd *generateCmd) Help() string {
@@ -71,11 +72,12 @@ func (cmd *generateCmd) Help() string {
 func (cmd *generateCmd) Flags() *flag.FlagSet {
 	fs := flag.NewFlagSet("generate", flag.ExitOnError)
 	fs.StringVar(&cmd.flagProviderName, "provider-name", "", "provider name, as used in Terraform configurations")
+	fs.StringVar(&cmd.flagProviderDir, "provider-dir", "", "relative or absolute path to the root provider code directory when running the command outside the root provider code directory")
 	fs.StringVar(&cmd.flagRenderedProviderName, "rendered-provider-name", "", "provider name, as generated in documentation (ex. page titles, ...)")
-	fs.StringVar(&cmd.flagRenderedWebsiteDir, "rendered-website-dir", "docs", "output directory")
-	fs.StringVar(&cmd.flagExamplesDir, "examples-dir", "examples", "examples directory")
+	fs.StringVar(&cmd.flagRenderedWebsiteDir, "rendered-website-dir", "docs", "output directory based on provider-dir")
+	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")
+	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.BoolVar(&cmd.flagIgnoreDeprecated, "ignore-deprecated", false, "don't generate documentation for deprecated resources and data-sources")
 	return fs
@@ -95,6 +97,7 @@ func (cmd *generateCmd) Run(args []string) int {
 func (cmd *generateCmd) runInternal() error {
 	err := provider.Generate(
 		cmd.ui,
+		cmd.flagProviderDir,
 		cmd.flagProviderName,
 		cmd.flagRenderedProviderName,
 		cmd.flagRenderedWebsiteDir,