DOCSEARCHbyAlgolia
Submit Docs

terraform-plugin-docs

repository·main·Indexed 42 days ago

https://github.com/hashicorp/terraform-plugin-docs

A collection of tools to automate the generation and validation of documentation for Terraform provider plugins. It features the tfplugindocs CLI, which allows developers to generate provider websites from source code and templates, validate documentation against Terraform Registry guidelines, and migrate legacy rendered websites into a supported template structure.

Tokens
7.3K
Snippets
9
Records
26
Agent score
52%

What's inside terraform-plugin-docs

  1. Overview of terraform-plugin-docs

    main
    The terraform-plugin-docs repository provides tools and packages specifically designed for creating documentation for Terraform plugins (currently supporting provider plugins). The primary interface for developers is the tfplugindocs CLI tool, which is used to automate the generation and validation of plugin documentation.

  2. Use the tfplugindocs CLI to manage plugin documentation

    main
    The tfplugindocs CLI is the main tool for interacting with this project. It allows you to generate documentation for your Terraform provider plugins and validate that the generated documentation meets the required standards.

  3. Use `tfplugindocs generate` to create provider documentation

    main

    The generate command (the default command) builds a provider website from your provider's source code, markdown templates, and .tf example files. It automatically builds a temporary provider binary, extracts the schema using terraform providers schema -json, and generates missing template files (like index.md, resource, or data source templates) if they are not present.

    Key flags:

    • --provider-dir: Path to the root provider code directory.
    • --provider-name: The name used in Terraform configurations.
    • --examples-dir: Directory containing .tf examples (defaults to examples).
    • --website-source-dir: Directory containing templates (defaults to templates).
    • --rendered-website-dir: Output directory for the generated website (defaults to docs).
    • --providers-schema: Path to a pre-generated schema JSON file. Using this skips the provider build and Terraform CLI calls.
    tfplugindocs generate

  4. Install the `tfplugindocs` CLI

    main

    You can install the tfplugindocs binary manually from the GitHub releases page. Alternatively, you can use the tools.go model to manage the installation within your Go project.

    To install using the tools.go method:

    1. Create a tools.go file in your repository with the following content:
    //go:build tools

package tools

import (
  _ "github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs"
)
    1. Run the following commands to install and verify the binary:
    export GOBIN=$PWD/bin
export PATH=$GOBIN:$PATH
go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
which tfplugindocs
    export GOBIN=$PWD/bin
export PATH=$GOBIN:$PATH
go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
which tfplugindocs

  5. Migrate legacy documentation with `tfplugindocs migrate`

    main

    The migrate command converts legacy rendered website files into the tfplugindocs supported templates/ structure. It can migrate from:

    • The legacy rendered website directory (website/docs/r)
    • The docs rendered website directory (docs/resources)

    Markdown files in the source directory will be converted into templates. It is recommended to remove the legacy website/ directory after migration to avoid Terraform Registry ingress issues.

    tfplugindocs migrate

  6. Validate provider documentation with `tfplugindocs validate`

    main

    The validate command checks your provider website against Terraform Registry documentation guidelines and best practices. It performs several automated checks:

    • InvalidDirectoriesCheck: Ensures valid subdirectory structure.
    • MixedDirectoriesCheck: Ensures you aren't mixing legacy (/website/docs) and registry (/docs) documentation.
    • FileSizeCheck: Ensures files are within registry storage limits.
    • FileExtensionCheck: Validates file extensions.
    • FrontMatterCheck: Validates YAML frontmatter (required fields, valid subcategories).
    • FileMismatchCheck: Ensures the number/names of documentation files match the provider schema.

    All errors are returned as a single message to stderr.

    tfplugindocs validate

  7. Use the `migrate` subcommand to convert rendered websites to templates

    main

    The migrate subcommand automates the conversion of a rendered website directory into a structured set of documentation templates and example files.

    The migration process performs the following steps:

    1. Determines the rendered website directory via --provider-dir and the provider name via --provider-name.
    2. Copies the rendered website contents to the --templates-dir folder.
    3. Legacy Support: If using the legacy format, it renames docs/d/ to data-sources/ and docs/r/ to resources/.
    4. Removes the provider shortname prefix from filenames in the --templates-dir.
    5. Converts Markdown files to .md.tmpl to create website templates.
    6. Extracts code blocks from the website docs into individual files in --examples-dir.
    7. Replaces extracted code in templates with codefile/tffile template functions that reference the new example files.
    8. Copies non-template files to --templates-dir and removes the original website/ directory.

  8. Template data fields for Providers

    main

    Templates are implemented using Go text/template. When working with Provider templates, the following data fields are available:

    FieldTypeDescription
    .DescriptionstringProvider description
    .HasExamplebool(Legacy) Is there an example file?
    .HasExamplesboolAre there example files? Always true if HasExample is true.
    .ExampleFilestring(Legacy) Path to the file with the Terraform configuration example.
    .ExampleFilesstringPaths to the files with the Terraform configuration example. Includes ExampleFile.
    .ProviderNamestringCanonical provider name (ex. terraform-provider-random)
    .ProviderShortNamestringShort version of the rendered provider name (ex. random)
    .RenderedProviderNamestringValue provided via argument --rendered-provider-name, otherwise same as .ProviderName
    .SchemaMarkdownstringA Markdown formatted Provider Schema definition

  9. Reference State Store fields

    main

    The following fields are available for state stores:

    FieldTypeDescription
    .NamestringName of the state store (ex. examplecloud_thing)
    .TypestringState Store
    .DescriptionstringState store description
    .HasExamplebool(Legacy) Is there an example file?
    .HasExamplesboolAre there example files? Always true if HasExample is true.
    .ExampleFilestring(Legacy) Path to the file with the terraform configuration example
    .ExampleFilesstringPaths to the files with terraform configuration examples. Includes ExampleFile.
    .ProviderNamestringCanonical provider name (ex. terraform-provider-http)
    .ProviderShortNamestringShort version of the rendered provider name (ex. http)
    .RenderedProviderNamestringValue provided via argument --rendered-provider-name, otherwise same as .ProviderName
    .SchemaMarkdownstringa Markdown formatted state store Schema definition

  10. Use template functions in terraform-plugin-docs

    main

    The tfplugindocs engine supports a variety of template functions used within Markdown files to manipulate text, format code, or inject file contents. These functions are used within double curly braces {{ ... }} and can be applied directly to values or via pipes | for transformations.

    | Function        | Example                                          | Description                                                                                       |
|-----------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------|
| `codefile`      | `{{codefile "shell" "path/to/file.sh"}}`         | Create a Markdown code block with the content of a file. Path is relative to the repository root. |
| `lower`         | `{{"EXAMPLE STRING" | lower}}`                  | Equivalent to [`strings.ToLower`](https://pkg.go.dev/strings#ToLower).                            |
| `plainmarkdown` | `{{"*example markdown*" | plainmarkdown }}`     | Render Markdown content as plaintext.                                                             |
| `prefixlines`   | `{{"example string" | prefixlines "prefix: "}}` | Add a prefix to all (newline-separated) lines in a string.                                        |
| `printf`        | `{{printf "{{tffile %q}}" .ExampleFile}}`      | Equivalent to [`fmt.Printf`](https://pkg.go.dev/fmt#Printf).                                      |
| `split`         | `{{split "example,string" ","}}`                 | Split string into sub-strings, by a given separator.                                                |
| `title`         | `{{"example string" | title}}`                  | Equivalent to [`cases.Title`](https://pkg.go.dev/golang.org/x/text/cases#Title).                          |
| `tffile`        | `{{tffile "path/to/tffile.tf"}}`                 | A special case of the `codefile` function, designed for Terraform files (i.e. `.tf`).             |
| `trimspace`     | `{{"example string" | trimspace}}`              | Equivalent to [`strings.TrimSpace`](https://pkg.go.dev/strings#TrimSpace).                            |
| `upper`         | `{{"example string" | upper}}`                  | Equivalent to [`strings.ToUpper`](https://pkg.go.dev/strings#ToUpper).                                |

  11. Reference: `tfplugindocs generate` flags

    main

    The following flags are available for the generate command:

    FlagDescription
    --examples-dir <ARG>examples directory based on provider-dir (default: "examples")
    --ignore-deprecated <ARG>don't generate documentation for deprecated resources and data-sources (default: "false")
    --provider-dir <ARG>relative or absolute path to the root provider code directory when running the command outside the root provider code directory
    --provider-name <ARG>provider name, as used in Terraform configurations; defaults to the --provider-dir short name (after removing terraform-provider- prefix)
    --providers-schema <ARG>path to the providers schema JSON file, which contains the output of the terraform providers schema -json command. Setting this flag will skip building the provider and calling Terraform CLI
    --rendered-provider-name <ARG>provider name, as generated in documentation (ex. page titles, ...); defaults to the --provider-name
    --rendered-website-dir <ARG>output directory based on provider-dir (default: "docs")
    --tf-version <ARG>terraform binary version to download. If not provided, will look for a terraform binary in the local environment. If not found in the environment, will download the latest version of Terraform
    --website-source-dir <ARG>templates directory based on provider-dir (default: "templates")
    --website-temp-dir <ARG>temporary directory (used during generation)

  12. Reference: `tfplugindocs migrate` flags

    main

    The following flags are available for the migrate command:

    FlagDescription
    --examples-dir <ARG>examples directory based on provider-dir (default: "examples")
    --provider-dir <ARG>relative or absolute path to the root provider code directory when running the command outside the root provider code directory
    --templates-dir <ARG>new website templates directory based on provider-dir; files will be migrated to this directory (default: "templates")
    --provider-name <ARG>provider name, as used in Terraform configurations; defaults to the --provider-dir short name (after removing terraform-provider- prefix)