yandex-cloud / terraform-provider-yandex

Terraform Provider ================== • Documentation: https://terraform-provider.yandexcloud.net Requirements ------------ • Terraform 0.12+ • Go 1.21 (to build the provider plugin) Building The Provider --------------------- Clone repository to: Enter the provider directory and build the provider Using the provider ---------------------- If you're building the provider, follow the instructions to install it as a plugin. After placing it into your plugins directory, run to initialize it. Documentation about the provider specific configuration options can be found on the provider's website. An example of using an installed provider from local directory: Write following config into Developing the Provider --------------------------- If you wish to work on the provider, you'll first need Go installed on your machine (version 1.11+ is *required*). You'll also need to correctly setup a GOPATH, as well as adding to your . To compile the provider, run . This will build the provider and put the provider binary in the directory. In order to test the provider, you can simply run . In order to run the full suite of Acceptance tests, run . *Note:* Acceptance tests create real resources, and often cost money to run. --- Documentation Guide Generation changelog Docs - https://wiki.yandex-team.ru/cloud/devel/yandex.cloud-instrumenty-publichnogo-api/zony-otvetsvennosti-komandy/generacija-changelog/ Our documentation generator follows a specific flow. Based on the documentation template and the description fields for resources/datasources and their schema fields in the Terraform provider, we generate the corresponding documentation. For every resource and data source defined in the Yandex provider, a documentation template is automatically generated. If your resource/datasource does not have a template, please run the following command: If it is a new service, first update . Example of a Generated Template For reference, you can view a generated template for container_repository. By default, these templates are generated automatically. However, if you want to enhance the documentation of your resource or data source, you can manually add or rewrite information in the template. To do this, you can use the available template fields and functions that the Terraform documentation generator will process. Adding Examples to Documentation You can enhance your resource documentation by adding more examples. For instance, here’s an example from the storage documentation template: Adding new service to terraform provider documentation If you add a new service, please update . The key in this file is the service path in the templates directory, and the value is the service name. This is used for grouping services on the documentation website. Then run the following command: On Mac M1 run the following command: Resolving Template Variables Here are some examples of how template variables resolve: • {{.Name}} resolves to yandex_dns_zone. • {{.Description}} resolves to Manages a DNS Zone.. • {{ .SchemaMarkdown }} resolves to the generated schema documentation, such as Schema .... General Recommendations To ensure consistency and completeness in your documentation: • **Example Usage:** Uncomment the following block and add examples of resource/data source usage in the specified path: • **Import Syntax:** Uncomment the following block and add examples of resource import in the specified path: Documentation Build and Publishing To build the documentation website locally, follow these steps: • First, install YFM: • Once installed, you can build your local version of the documentation by running the following command: • To publish updates to the documentation, set the following environment variables: Then, run the following command: Documentation Migration Guide To migrate your document template to automatically generate resource/data source schema documentation, follow these steps: • **Add a Description:** Add a description to your resource in the Terraform provider. Example: dns_zone. • **Describe Schema Fields:** Add a description to every schema field for the resource/data source. Example: dns_zone.zone. • **Remove Manual Documentation:** • Remove the manual description of the resource/data source in the template. Example: datasource. • Remove the block. Example: Argument Reference. • Remove the block. Example: Attributes Reference. • **Automate Schema Documentation:** Place the field in the template to automatically generate documentation based on field descriptions. Fixing Markdown Issues Ensure that the markdown used in your documentation is properly formatted for consistent display and readability. This includes checking for proper syntax, resolving template variables, and ensuring that links and examples are correctly referenced.