Duplicate docs are generated when template names have <provider-name>_ prefix

[ctreatma]

Terraform CLI and terraform-plugin-docs Versions

$ terraform version
Terraform v1.5.7
on darwin_arm64

$ tfplugindocs --version
tfplugindocs Version 0.18.0 from commit 4c08c0eed13b3819b4342dc0cb119b3be62305b1

Provider Code

I'm attempting to run `tfplugindocs --migrate` followed by `tfplugindocs --generate` to convert existing provider docs from hand-written to generated: https://github.com/equinix/terraform-provider-equinix

Expected Behavior

The generator creates one Markdown page per resource or data source

Actual Behavior

The generator creates two Markdown pages per resource or data source: one page has the provider name prefix in the file name and the other does not

Steps to Reproduce

1. Create templates that match the documented conventional paths (for example, according to that, a template for caller_identity in the aws provider would be named aws_caller_identity.md.tmpl)
2. Run tfplugindocs --generate

I'm using tfplugindocs --migrate to create templates from existing docs; it produces the expected templates that have the conventional path with the provider name prefix.

The generator produces files that match the template names and have the expected contents, but it also produces files without the provider name prefix that use a default template.

Note: I confirmed that if I remove the provider prefix from the template files I only get the files without the provider name prefix, but I want to get one set of generated files that has the conventional path with the provider name prefix.

How much impact is this issue causing?

High

Logs

No response

Additional Information

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[bflad]

Hi @ctreatma 👋 Thank you for reporting this and sorry you ran into trouble here. I can reproduce this behavior via:

gh repo clone equinix/terraform-provider-equinix
cd terraform-provider-equinix
tfplugindocs migrate
go generate ./...
git status

I'm guessing there are at least two mutually exclusive options here:

• Having the migrate subcommand detect the provider name prefixed files and move them automatically to the "expected" location
• Having the generate subcommand detect the provider name prefixed files and treat them as equivalent to the "expected" location by overwriting the existing files instead of creating new files

Adjusting the migrate subcommand feels slightly more appropriate in this situation since the Terraform Registry does not particularly care the exact filenames when ingressing the documentation (only the file extensions) and since the intention of the migrate subcommand is to prepare the codebase for the generate subcommand. I could also see the argument for reducing potential file churn during the migration process at the expense of maintaining the additional logic in the tool during generation too.

[ctreatma]

When you refer to the "expected" location, which file path format are you referring to? Based on the documentation of conventional paths, I think the expected path is the one with the provider prefix (e.g., aws_caller_identity.md). Does that match what you have in mind, or are you referring to the un-prefixed path caller_identity.md as the expected path?

My aim would be to keep the provider prefix so that the docs don't move as a result of adopting docs generation: in the event that someone has bookmarked the existing pages I'd like to avoid throwing 404s and leaving them to find the page again. Would it be possible/feasible to add a flag to generate and/or migrate to explicitly adopt either the prefixed or un-prefixed path? (In that case I imagine the name of the flag would depend on which path is the default.)

[bflad]

It seems there is conflict/ambiguity between https://github.com/hashicorp/terraform-plugin-docs/?tab=readme-ov-file#conventional-paths and https://developer.hashicorp.com/terraform/registry/providers/docs#navigation-hierarchy, which is unfortunate. For what its worth as a "convention", many of the official and partner tier providers already tend to use non-prefixed resource filenames/paths, at least in the final documentation:

• https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/r2_bucket
• https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/monitor
• https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/s3_bucket
• https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_account
• https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/storage_bucket
• https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/manifest
• https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/pet
• https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository
• https://registry.terraform.io/providers/oracle/oci/latest/docs/resources/containerengine_cluster

This tooling is intended to be opinionated so it seems like it should lean towards following that ecosystem "convention" by default. As far as I am aware, the public Terraform Registry does not support provider-defined documentation redirects or the ability to "hide" pages from the side navigation, which makes preventing the /latest URLs from changing in your situation difficult if the original final paths change without keeping duplicate documentation and navigation. I will reach out internally to see if we might want to consider either of those features though.

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.