Implement Documentation Generation
In this tutorial, you will add documentation generation capabilities to a provider that interacts with the API of a fictional coffee-shop application called HashiCups. To do this, you will:
- Add terraform-plugin-docs to the provider.
This enables the provider to automatically generate data source and resource documentation. - Add schema descriptions.
This enhances the documentation to include a description for the provider itself, its data sources and resources, and each of their attributes. - Add configuration examples.
This enhances the documentation to include example Terraform configurations. - Add resource import documentation.
This enhances the resource documentation to include an example of how to import the resources that support it. - Run documentation generation.
This ensures that the documentation generation works as expected.
The terraform-plugin-docs
Go module cmd/tfplugindocs
command enables providers to implement documentation generation. The generation uses schema descriptions and conventionally placed files to produce provider documentation that is compatible with the Terraform Registry.
Prerequisites
To follow this tutorial, you need:
- Go 1.19+ installed and configured.
- Terraform v1.0.3+ installed locally.
Navigate to your terraform-provider-hashicups-pf
directory.
Your code should match the acceptance-tests
branch
from the example repository.
If you're stuck at any point during this tutorial, refer to the documentation-generation
branch to see the changes implemented in this tutorial.
Add schema descriptions
The tfplugindocs
tool will automatically include schema-based descriptions, if
present in a data source, provider, or resource's schema. The schema.Schema
type's Description
field describes the data source, provider, or resource
itself. Each attribute's or block's Description
field describes that
particular attribute or block. These descriptions should be tailored to
practitioner usage and include any caveats or value expectations, such as
special syntax.
Open the internal/provider/provider.go
file.
Add documentation to your provider by replacing the entire Schema
method
with the following, which adds Description
fields to the provider's schema and
each of it's attributes.
Open the internal/provider/coffees_data_source.go
file.
Add documentation to your data source by replacing the entire Schema
method
with the following.
Open the internal/provider/order_resource.go
file.
Add documentation to your resource by replacing the entire Schema
method
with the following.
Add configuration examples
The tfplugindocs
tool will automatically include Terraform configuration
examples from files with the following naming conventions:
- Provider:
examples/provider/provider.tf
- Resources:
examples/resources/TYPE/resource.tf
- Data Sources:
examples/data-sources/TYPE/data-source.tf
Replace TYPE
with the name of the resource or data source. For example:
examples/resources/hashicups_order/resource.tf
.
Open the examples/provider/provider.tf
file and replace the existing code with the following.
Create a examples/data-sources/hashicups_coffees
directory.
Create the examples/data-sources/hashicups_coffees/data-source.tf
file with the following.
Create the examples/resources/hashicups_order
directory.
Create the examples/resources/hashicups_order/resource.tf
file with the following.
Add resource import documentation
The tfplugindocs
tool automatically will include Terraform import examples for
resources with the file naming convention examples/resources/TYPE/import.sh
.
Create a new examples/resources/hashicups_order/import.sh
file with the following.
Run documentation generation
Now that you have implemented the documentation generation functionality for your provider, run the go generate ./...
command to generate the documentation.
View the generated files in the docs
directory to verify that the data source, provider, and resource documentation contains the expected descriptions, examples, and schema information.
Next steps
Congratulations! You have enhanced the provider with documentation generation capabilities.
If you were stuck during this tutorial, checkout the
documentation-generation
branch to see the changes implemented in this tutorial.
- To learn more about the Terraform Plugin Framework, refer to the Terraform Plugin Framework documentation.
- For a full capability comparison between the SDKv2 and the Plugin Framework, refer to the Which SDK Should I Use? documentation.
- The Terraform HashiCups (plugin-framework)
provider's
main
branch contains the complete HashiCups provider. It includes a data source written with the plugin framework and implements create, read, update and delete functionality for the order resource. - Submit any Terraform Plugin Framework bug reports or feature requests to the development team in the Terraform Plugin Framework Github repository.
- Submit any Terraform Plugin Framework questions in the Terraform Plugin Framework Discuss forum.