Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
117 lines (91 loc) · 4.68 KB

DOCUMENTATION.md

File metadata and controls

117 lines (91 loc) · 4.68 KB

Provider Documentation

Building and Reviewing

The documentation is built from templates stored in the templates folder, along with examples stored in the examples folder. All of this content is copied to the docs folder, with the templates fully rendered, when the documentation is built.

To validate the templates directory structure and its references to schemas in the provider and to examples, run:

make validate-docs

To build the documentation, replacing all of the contents of the docs folder:

make generate-docs

To preview a single documentation file, copy the content of the generated Markdown file into the preview tool on the HashiCorp website.

Templates

Every resource and data source in the provider has its own documentation, which includes details of making use of that resource/data source, along with the details of its schema.

If you do not write a template for a resource or data source that you create, make generate-docs will use a basic template to generate the documentation for the provider. This template will include only the name of the resource/data source and the details of its schema. For resources in particular, this is insufficient to guide users as it does not include examples of HCL which make use of the resource, or instructions for how to import an existing resource into the Terraform state.

Note: The documentation generation tool gathers the list of known data sources and resources from the provider itself, not by scanning the source directory. As a result, if you have created a new data source or resource but you have not added into the top-level schema in provider.go it will not be included in the generated documentation. If you create a template for the new data source or resource and run make validate-docs the validator will produce an error as it will be unable to find the new data source or resource. The simplest way to avoid this problem is to write and execute the acceptance tests for the new data source or resource before working on its documentation; in order for the acceptance tests to pass the new data source or resource must already be included in the top-level schema.

Before submitting a PR with your new data source or resource, you should add a proper template for it, and also ensure that the schema within the data source or resource has been properly documented as well. Review the following three sections for details.

Data Sources

Each data source should have a template file and an example file showing basic usage of the data source in HCL. The template for NGWAF Workspaces can be used as a reference.

Resources

Each resource should have a template file and at least two example files: one showing basic usage of the resource in HCL, and the other demonstrating how to import an existing resource into the Terraform state. The examples should be fully functional: they should include all resources necessary to create the resource being documented. The template for Config Stores can be used as a reference.

Schema Attributes

Every attribute in every schema must include a description. The description should provide all of the information necessary for a user to understand the purpose and usage of that attribute.

To write consistent and helpful attribute descriptions, follow these steps:

  1. Use the description (from the public documentation) of the corresponding attribute of the API resource that the schema represents, whenever possible.

  2. If the attribute allows only a limited set of values (an enumeration), include a sentence such as "Accepted values are value 1, value 2, and value 3". If the attribute is read-only (as it would be in a data source, use "One of/or" instead of "Accepted values are/and").

  3. If the attribute allows only a range of values (numeric), include a sentence such as "Minimum 1 and maximum 10,000".

  4. If the attribute has a default value, include a sentence such as "Default value value".

  5. If the attribute's value is an ID which can be obtained from another data source or resource, include a sentence such as "Can be obtained from fastly_service_vcl, fastly_service_compute, or fastly_services".

  6. There is no need to include information about the attribute being optional, computed, or read-only, as the schema documentation generator will include that information in the documentation of the attribute.

Composing a description by following these steps, in this order, will result in a consistent presentation for the user of the data source or resource.