Terraform Docs: Example File Naming Convention

Dec 16, 2025 by Alex Johnson 47 views

When working with Terraform and generating documentation for your providers, you might run into a peculiar constraint regarding example files. Specifically, the terraform-plugin-docs tool, which is instrumental in creating comprehensive documentation, has a naming convention for example files that can feel a bit redundant. This article dives into this specific naming constraint, why it exists, and how you can navigate it to ensure your Terraform examples are correctly documented. We'll explore the expected behavior versus the actual behavior you might encounter and provide clear steps to reproduce the issue, along with an understanding of its impact.

Understanding the `terraform-plugin-docs` Example Naming Convention

Let's start by discussing the expected behavior when you're documenting your Terraform provider. Ideally, you'd want terraform-plugin-docs to pick up any .tf file within your designated example directories, regardless of its specific name. For instance, if you have a folder structure for your examples and a file named foobar.tf, you'd anticipate this file being recognized and its content being incorporated into the generated documentation. The reasoning behind this expectation is that the directory structure itself often provides enough context to identify the nature of the example. If an example resides within a folder clearly marked for resources, the tool should logically infer that foobar.tf is indeed a resource example. However, the reality with terraform-plugin-docs is a bit different. The tool imposes a stricter naming convention for example files, requiring them to start with a specific prefix to be recognized. This can lead to a situation where perfectly valid Terraform configuration files are overlooked, simply because they don't adhere to this particular naming rule. This is the core of the redundant naming constraint we're discussing.

The Actual Behavior You Might Encounter

Now, let's talk about the actual behavior you're likely to observe when using terraform-plugin-docs with the default settings. Instead of automatically picking up files like foobar.tf, you'll find that these files are ignored during the documentation generation process. To get your examples included, you'll need to rename them to comply with the tool's specific requirement. The common convention here is to prepend a prefix, often resource-, to your example file names. So, that foobar.tf file would need to be renamed to resource-foobar.tf for terraform-plugin-docs to recognize it and process it for your documentation. This means that even if your directory structure clearly indicates that the file is an example for a resource, the filename itself must explicitly signal this to the tool. This requirement, while seemingly minor, can be a point of confusion and frustration for users who expect a more flexible system. It adds an extra step to the workflow and can feel like an unnecessary hurdle, especially when the context is already available through other means, such as the file's location within the project structure. Understanding this discrepancy between what you might expect and what actually happens is crucial for effectively using terraform-plugin-docs.

Steps to Reproduce the Naming Constraint Issue

Reproducing this issue is quite straightforward and can be achieved with a simple command. The process involves having a Terraform provider project set up with example files in a structured manner, and then running the terraform-plugin-docs generation command. Here’s how you can reproduce the problem:

Set up your provider project: Ensure you have a basic Terraform provider project structure. Within this structure, create a directory for your examples. A common place for this is a folder named examples. Inside this examples folder, you might create subdirectories for different types of examples, such as resources or data_sources.
Create an example file: Within one of these example subdirectories (e.g., examples/resources/), create a standard Terraform configuration file. Let's name this file foobar.tf. This file can contain a simple Terraform resource block, for instance:
```
resource "null_resource" "example" {
  triggers = {
    "always_run" = timestamp()
  }
}
```
Run tfplugindocs generate: Navigate to the root of your Terraform provider project in your terminal. Execute the terraform-plugin-docs generation command. The command you'll likely use is tfplugindocs generate --flags (or simply tfplugindocs generate if you don't need specific flags).
Observe the output: After the command completes, examine the generated documentation files. You will likely notice that the example file foobar.tf has not been included or referenced in the documentation. The tool has effectively ignored it.
Rename the file: Now, rename the foobar.tf file to resource-foobar.tf.
Run tfplugindocs generate again: Execute the same tfplugindocs generate --flags command once more.
Observe the corrected output: Upon re-generating the documentation, you should now find that the example, previously named foobar.tf and now resource-foobar.tf, is correctly picked up and included in the documentation. This demonstrates the specific filename prefix requirement.

This straightforward reproduction process highlights the redundant naming constraint imposed by terraform-plugin-docs, where the filename prefix is a critical factor for file recognition, even when the directory structure provides contextual clues.

The Rationale Behind the Naming Convention

While the requirement to prepend resource- (or similar prefixes) to example files might seem redundant, there's often a logical reason behind such conventions in software tooling. For terraform-plugin-docs, this strict naming requirement helps the tool to unambiguously parse and categorize the example files. The primary goal of terraform-plugin-docs is to generate accurate and well-structured documentation for your Terraform provider, including details about resources, data sources, and examples. By enforcing a naming convention like resource-<name>.tf, datasource-<name>.tf, or examples-<name>.tf, the tool can programmatically identify the type of construct each file represents without needing to deeply analyze its content or rely solely on directory structure, which can be more complex and prone to errors. This approach simplifies the parsing logic and ensures consistency across different providers and projects. It acts as a clear signal to the generator: 'This file is an example related to a resource.' This explicit labeling reduces ambiguity and helps prevent misclassification, especially in complex provider projects with numerous files and intricate directory layouts. Furthermore, this convention can be beneficial for future enhancements of the tool. Having such explicit naming allows for more sophisticated features to be added later, such as automatically linking examples to their corresponding resource documentation or providing specialized rendering for different example types. It provides a clear contract between the user and the tool. Although it might feel like an extra step for the user, it contributes to the robustness and maintainability of the generated documentation. The low impact noted by users often stems from the fact that renaming files is a relatively minor task, but understanding the underlying 'why' can help in accepting and integrating this convention into your workflow.

Assessing the Impact of the Constraint

The impact of this redundant naming constraint on Terraform provider development and documentation is generally considered low. This assessment is primarily due to the nature of the task itself. Renaming files is a relatively minor and straightforward operation within a development workflow. While it adds an extra step, it doesn't fundamentally alter the structure of the provider code or the examples themselves. Developers often encounter similar minor conventions in various tools and platforms, and adapting to them is usually a quick learning process. The core functionality of the Terraform provider remains unaffected. The examples still function correctly, and the documentation is ultimately generated with the required information. The main inconvenience lies in the initial discovery of this rule and the potential for overlooked examples if the naming convention isn't followed. For new users or those unfamiliar with terraform-plugin-docs, it can lead to a brief period of confusion where their examples don't appear as expected. However, once the convention is understood, it becomes a routine part of the documentation generation process. The low impact also means that this is not typically a blocker for releasing providers or for maintaining them. It's more of a usability friction point than a significant impediment. In many cases, teams might adopt this naming convention from the outset, especially if they are aware of terraform-plugin-docs's requirements, thereby mitigating any potential issues. The fact that the file path can be used to infer context highlights why the constraint feels redundant, but the tool's design prioritizes explicit naming for clarity and robustness in parsing. Therefore, while not ideal from a pure flexibility standpoint, the practical consequences of this specific naming rule are minimal for most users.

Navigating the Naming Convention in Your Workflow

To effectively manage the redundant naming constraint and ensure your Terraform examples are always documented correctly, integrating the resource- prefix (or the appropriate prefix for data sources, etc.) into your development workflow is key. When you're creating new examples, make it a habit to name your files according to the terraform-plugin-docs convention from the start. For instance, if you are documenting a new aws_s3_bucket resource, your example file should be named something like resource-aws_s3_bucket.tf. Similarly, for data sources, you would use a prefix like data-source-. While the tool might eventually pick up files without the prefix if they are in the correct directory, relying on this is risky and can lead to missed documentation. The explicit naming serves as a clear indicator to the tool, streamlining the documentation generation process. If you are working on an existing project where examples have been added without the correct prefix, you will need to perform a one-time rename operation. As demonstrated in the 'Steps to Reproduce' section, simply renaming the files and re-running tfplugindocs generate will resolve the issue. It's also a good practice to include this convention in your team's contribution guidelines if you're working collaboratively. This ensures that everyone contributing to the provider's documentation understands and adheres to the required naming standards. While the necessity of the prefix might be debated, understanding and applying it is the most efficient way to ensure your Terraform provider documentation is complete and accurate. This proactive approach minimizes friction and maximizes the value you get from documentation generation tools.

Conclusion: Embracing Clarity in Documentation

In conclusion, the redundant naming constraint observed in terraform-plugin-docs for example files, requiring prefixes like resource-, serves a practical purpose in ensuring clarity and robustness in the automated documentation generation process. While it might initially seem like an unnecessary hurdle, especially when directory structures can offer contextual clues, this explicit naming convention simplifies parsing for the tool, reduces ambiguity, and provides a consistent framework for documentation. The impact of this constraint is generally low, as renaming files is a minor adjustment in the overall development workflow. By understanding the rationale behind this convention and integrating it into your development practices, you can ensure that your Terraform examples are correctly captured and presented in your provider documentation. This adherence to tooling conventions ultimately leads to more complete, accurate, and user-friendly documentation for your Terraform providers. It's a small price to pay for the benefits of automated, structured documentation.

For more in-depth information on Terraform and provider development best practices, consider exploring the official Terraform Registry documentation. You can also find valuable insights and community discussions on the HashiCorp Discuss forums.