Strip Provider Prefix from File Names during Migration (#349)

* Add `--provider-name` flag to `migrate` subcommand and strip provider short name prefix during migration * Update README.md * Add changelog entries * Default the `--provider-name` flag to use the provider directory basename * Update .changes/unreleased/ENHANCEMENTS-20240327-160831.yaml Co-authored-by: Brian Flad <[email protected]> --------- Co-authored-by: Brian Flad <[email protected]>
hashicorp · Mar 28, 2024 · e3fab9a · e3fab9a
1 parent 836a890
commit e3fab9a
Show file tree

Hide file tree

Showing 7 changed files with 1,980 additions and 14 deletions.
diff --git a/.changes/unreleased/BUG FIXES-20240327-161037.yaml b/.changes/unreleased/BUG FIXES-20240327-161037.yaml
@@ -0,0 +1,6 @@
+kind: BUG FIXES
+body: 'migrate: fixed a bug where documentation files with provider name prefixes were
+  migrated to templates directory as-is, causing `generate` to create duplicate templates'
+time: 2024-03-27T16:10:37.029568-04:00
+custom:
+  Issue: "349"
diff --git a/.changes/unreleased/ENHANCEMENTS-20240327-160831.yaml b/.changes/unreleased/ENHANCEMENTS-20240327-160831.yaml
@@ -0,0 +1,6 @@
+kind: ENHANCEMENTS
+body: 'migrate: Added `--provider-name` flag to override the default provider name when any
+  file names that contain provider name prefixes are removed during migration'
+time: 2024-03-27T16:08:31.541882-04:00
+custom:
+  Issue: "349"
diff --git a/README.md b/README.md
@@ -98,6 +98,7 @@ Usage: tfplugindocs migrate [<args>]
     --examples-dir <ARG>             examples directory based on provider-dir                                                                                           (default: "examples")
     --provider-dir <ARG>             relative or absolute path to the root provider code directory when running the command outside the root provider code directory
     --templates-dir <ARG>            new website templates directory based on provider-dir; files will be migrated to this directory                                    (default: "templates")
+    --provider-name <ARG>            provider name, as used in Terraform configurations; this will default to provider-dir basename if not set                                                                                                                                            
 ```
 
 ### How it Works
@@ -175,23 +176,24 @@ ingress issues.
 
 The `migrate` subcommand takes the following actions:
 1. Determines the rendered website directory based on the `--provider-dir` argument
-2. Copies the contents of the rendered website directory to the `--templates-dir` folder (will create this folder if it doesn't exist)
-3. (if the rendered website is using legacy format) Renames `docs/d/` and `docs/r/` subdirectories to `data-sources/` and `resources/` respectively
-4. Change file suffixes for Markdown files to `.md.tmpl` to create website templates
-5. Extracts code blocks from website docs to create individual example files in `--examples-dir` (will create this folder if it doesn't exist)
-6. Replace extracted example code in website templates with `codefile`/`tffile` template functions referencing the example files.
-7. Copies non-template files to `--templates-dir` folder
-8. Removes the `website/` directory
+2. Determines the provider name based on the `--provider-name` argument
+3. Copies the contents of the rendered website directory to the `--templates-dir` folder (will create this folder if it doesn't exist)
+4. (if the rendered website is using legacy format) Renames `docs/d/` and `docs/r/` subdirectories to `data-sources/` and `resources/` respectively
+5. Renames files in the `--templates-dir` folder to remove the provider shortname prefix from the file name
+6. Change file suffixes for Markdown files to `.md.tmpl` to create website templates
+7. Extracts code blocks from website docs to create individual example files in `--examples-dir` (will create this folder if it doesn't exist)
+8. Replace extracted example code in website templates with `codefile`/`tffile` template functions referencing the example files.
+9. Copies non-template files to `--templates-dir` folder
+10. Removes the `website/` directory
 
 ### Conventional Paths
 
 The generation of missing documentation is based on a number of assumptions / conventional paths.
 
-> **NOTE:** In the following conventional paths, `<data source name>` and `<resource name>` include the provider prefix as well, but the provider prefix is **NOT** included in`<function name>`.
-> For example, the data source [`caller_identity`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) in the `aws` provider would have an "example" conventional path of: `examples/data-sources/aws_caller_identity/data-source.tf`
-
 For templates:
 
+> **NOTE:** In the following conventional paths for templates, `<data source name>`, `<resource name>`, and `<function name>` do not include the provider prefix.
+
 | Path                                                  | Description                            |
 |-------------------------------------------------------|----------------------------------------|
 | `templates/`                                          | Root of templated docs                 |
@@ -207,6 +209,9 @@ Note: the `.tmpl` extension is necessary, for the file to be correctly handled a
 
 For examples:
 
+> **NOTE:** In the following conventional paths for examples, `<data source name>` and `<resource name>` include the provider prefix as well, but the provider prefix is **NOT** included in`<function name>`.
+> For example, the data source [`caller_identity`](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) in the `aws` provider would have an "example" conventional path of: `examples/data-sources/aws_caller_identity/data-source.tf`
+
 | Path                                                      | Description                     |
 |-----------------------------------------------------------|---------------------------------|
 | `examples/`                                               | Root of examples                |
@@ -220,6 +225,9 @@ For examples:
 
 The `migrate` subcommand assumes the following conventional paths for the rendered website directory:
 
+> **NOTE:** In the following conventional paths for templates, `<data source name>`, `<resource name>`, and `<function name>` do not include the provider prefix.
+> if the `--provider-name` argument is set, the provider prefix will be removed from the file names during migration.
+
 Legacy website directory structure:
 
 | Path                                                  | Description                 |