template.go

// Copyright IBM Corp. 2020, 2026
// SPDX-License-Identifier: MPL-2.0

package provider

import (
	"bytes"
	"fmt"
	"io"
	"path/filepath"
	"strings"
	"text/template"

	"golang.org/x/text/cases"
	"golang.org/x/text/language"

	tfjson "github.com/hashicorp/terraform-json"

	"github.com/hashicorp/terraform-plugin-docs/internal/schemamd"

	"github.com/hashicorp/terraform-plugin-docs/internal/functionmd"
	"github.com/hashicorp/terraform-plugin-docs/internal/mdplain"
	"github.com/hashicorp/terraform-plugin-docs/internal/tmplfuncs"
)

const (
	schemaComment    = "<!-- schema generated by tfplugindocs -->"
	signatureComment = "<!-- signature generated by tfplugindocs -->"
	argumentComment  = "<!-- arguments generated by tfplugindocs -->"
	variadicComment  = "<!-- variadic argument generated by tfplugindocs -->"

	frontmatterComment = "# generated by https://github.com/hashicorp/terraform-plugin-docs"
)

type (
	resourceTemplate string
	functionTemplate string
	providerTemplate string

	docTemplate string
)

type ResourceTemplateType struct {
	Type        string
	Name        string
	Description string

	HasExample   bool
	HasExamples  bool
	ExampleFile  string
	ExampleFiles []string

	HasImport  bool
	ImportFile string

	HasImportIDConfig  bool
	ImportIDConfigFile string

	HasImportIdentityConfig  bool
	ImportIdentityConfigFile string
	IdentitySchemaMarkdown   string

	ProviderName      string
	ProviderShortName string

	SchemaMarkdown string

	RenderedProviderName string
}

type ProviderTemplateType struct {
	Description string

	HasExample   bool
	HasExamples  bool
	ExampleFile  string
	ExampleFiles []string

	ProviderName      string
	ProviderShortName string
	SchemaMarkdown    string

	RenderedProviderName string
}

type FunctionTemplateType struct {
	Type        string
	Name        string
	Description string
	Summary     string

	HasExample   bool
	HasExamples  bool
	ExampleFile  string
	ExampleFiles []string

	ProviderName      string
	ProviderShortName string

	FunctionSignatureMarkdown string
	FunctionArgumentsMarkdown string

	HasVariadic                      bool
	FunctionVariadicArgumentMarkdown string

	RenderedProviderName string
}

func newTemplate(providerDir, name, text string) (*template.Template, error) {
	tmpl := template.New(name)
	titleCaser := cases.Title(language.Und)

	tmpl.Funcs(map[string]interface{}{
		"codefile":      codeFile(providerDir),
		"lower":         strings.ToLower,
		"plainmarkdown": mdplain.PlainMarkdown,
		"prefixlines":   tmplfuncs.PrefixLines,
		"split":         strings.Split,
		"tffile":        terraformCodeFile(providerDir),
		"title":         titleCaser.String,
		"trimspace":     strings.TrimSpace,
		"upper":         strings.ToUpper,
	})

	var err error
	tmpl, err = tmpl.Parse(text)
	if err != nil {
		return nil, fmt.Errorf("unable to parse template %q: %w", text, err)
	}

	return tmpl, nil
}

func codeFile(providerDir string) func(string, string) (string, error) {
	return func(format string, file string) (string, error) {
		if filepath.IsAbs(file) {
			return tmplfuncs.CodeFile(format, file)
		}

		return tmplfuncs.CodeFile(format, filepath.Join(providerDir, file))
	}
}

func terraformCodeFile(providerDir string) func(string) (string, error) {
	// TODO: omit comment handling
	return func(file string) (string, error) {
		if filepath.IsAbs(file) {
			return tmplfuncs.CodeFile("terraform", file)
		}

		return tmplfuncs.CodeFile("terraform", filepath.Join(providerDir, file))
	}
}

func renderTemplate(providerDir, name string, text string, out io.Writer, data interface{}) error {
	tmpl, err := newTemplate(providerDir, name, text)
	if err != nil {
		return err
	}

	err = tmpl.Execute(out, data)
	if err != nil {
		return fmt.Errorf("unable to execute template: %w", err)
	}

	return nil
}

func renderStringTemplate(providerDir, name, text string, data interface{}) (string, error) {
	var buf bytes.Buffer

	err := renderTemplate(providerDir, name, text, &buf, data)
	if err != nil {
		return "", err
	}

	return buf.String(), nil
}

func (t docTemplate) Render(providerDir string, out io.Writer) error {
	s := string(t)
	if s == "" {
		return nil
	}

	return renderTemplate(providerDir, "docTemplate", s, out, nil)
}

func (t providerTemplate) Render(providerDir, providerName, renderedProviderName, exampleFile string, exampleFiles []string, schema *tfjson.Schema, blocksSection bool) (string, error) {
	schemaBuffer := bytes.NewBuffer(nil)
	err := schemamd.Render(schema, schemaBuffer, blocksSection)
	if err != nil {
		return "", fmt.Errorf("unable to render schema: %w", err)
	}

	s := string(t)
	if s == "" {
		return "", nil
	}

	return renderStringTemplate(providerDir, "providerTemplate", s, ProviderTemplateType{
		Description: schema.Block.Description,

		HasExample:   exampleFile != "" && fileExists(exampleFile),
		HasExamples:  len(exampleFiles) > 0,
		ExampleFile:  exampleFile,
		ExampleFiles: exampleFiles,

		ProviderName:      providerName,
		ProviderShortName: providerShortName(renderedProviderName),

		SchemaMarkdown: schemaComment + "\n" + schemaBuffer.String(),

		RenderedProviderName: renderedProviderName,
	})
}

func (t resourceTemplate) Render(providerDir, name, providerName, renderedProviderName, typeName, exampleFile string, exampleFiles []string, importIDConfigFile, importIdentityConfigFile, importCmdFile string, schema *tfjson.Schema, identitySchema *tfjson.IdentitySchema, blocksSection bool) (string, error) {
	schemaBuffer := bytes.NewBuffer(nil)
	err := schemamd.Render(schema, schemaBuffer, blocksSection)
	if err != nil {
		return "", fmt.Errorf("unable to render schema: %w", err)
	}

	s := string(t)
	if s == "" {
		return "", nil
	}

	hasImportIdentityConfig := importIdentityConfigFile != "" && fileExists(importIdentityConfigFile)
	identitySchemaBuffer := bytes.NewBuffer(nil)

	// Always render the identity schema if we have one, so it can be used in custom templates.
	if identitySchema != nil {
		_, err := io.WriteString(identitySchemaBuffer, schemaComment+"\n")
		if err != nil {
			return "", fmt.Errorf("unable to render identity schema comment: %w", err)
		}

		err = schemamd.RenderIdentitySchema(identitySchema, identitySchemaBuffer)
		if err != nil {
			return "", fmt.Errorf("unable to render identity schema: %w", err)
		}
	} else if hasImportIdentityConfig {
		// If there is an identity example, but we don't have an identity schema, we should return an error to ensure the example file was intended.
		return "", fmt.Errorf("unable to render: an identity import example (%q) was provided for a resource (%q) that does not support resource identity", importIdentityConfigFile, name)
	}

	return renderStringTemplate(providerDir, "resourceTemplate", s, ResourceTemplateType{
		Type:        typeName,
		Name:        name,
		Description: schema.Block.Description,

		HasExample:   exampleFile != "" && fileExists(exampleFile),
		HasExamples:  len(exampleFiles) > 0,
		ExampleFile:  exampleFile,
		ExampleFiles: exampleFiles,

		HasImport:  importCmdFile != "" && fileExists(importCmdFile),
		ImportFile: importCmdFile,

		HasImportIDConfig:  importIDConfigFile != "" && fileExists(importIDConfigFile),
		ImportIDConfigFile: importIDConfigFile,

		HasImportIdentityConfig:  hasImportIdentityConfig,
		ImportIdentityConfigFile: importIdentityConfigFile,
		IdentitySchemaMarkdown:   identitySchemaBuffer.String(),

		ProviderName:      providerName,
		ProviderShortName: providerShortName(renderedProviderName),

		SchemaMarkdown: schemaComment + "\n" + schemaBuffer.String(),

		RenderedProviderName: renderedProviderName,
	})
}

func (t functionTemplate) Render(providerDir, name, providerName, renderedProviderName, typeName, exampleFile string, exampleFiles []string, signature *tfjson.FunctionSignature) (string, error) {
	funcSig, err := functionmd.RenderSignature(name, signature)
	if err != nil {
		return "", fmt.Errorf("unable to render function signature: %w", err)
	}

	funcArgs, err := functionmd.RenderArguments(signature)
	if err != nil {
		return "", fmt.Errorf("unable to render function arguments: %w", err)
	}

	funcVarArg, err := functionmd.RenderVariadicArg(signature)
	if err != nil {
		return "", fmt.Errorf("unable to render variadic argument: %w", err)
	}

	s := string(t)
	if s == "" {
		return "", nil
	}

	return renderStringTemplate(providerDir, "resourceTemplate", s, FunctionTemplateType{
		Type:        typeName,
		Name:        name,
		Description: signature.Description,
		Summary:     signature.Summary,

		HasExample:   exampleFile != "" && fileExists(exampleFile),
		HasExamples:  len(exampleFiles) > 0,
		ExampleFile:  exampleFile,
		ExampleFiles: exampleFiles,

		ProviderName:      providerName,
		ProviderShortName: providerShortName(renderedProviderName),

		FunctionSignatureMarkdown: signatureComment + "\n" + funcSig,
		FunctionArgumentsMarkdown: argumentComment + "\n" + funcArgs,

		HasVariadic:                      signature.VariadicParameter != nil,
		FunctionVariadicArgumentMarkdown: variadicComment + "\n" + funcVarArg,

		RenderedProviderName: renderedProviderName,
	})
}

const defaultResourceTemplate resourceTemplate = `---
` + frontmatterComment + `
page_title: "{{.Name}} {{.Type}} - {{.RenderedProviderName}}"
subcategory: ""
description: |-
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
---

# {{.Name}} ({{.Type}})

{{ .Description | trimspace }}

{{ if .HasExamples -}}
## Example Usage

{{- range .ExampleFiles }}

{{ tffile . }}
{{- end }}
{{- end }}

{{ .SchemaMarkdown | trimspace }}
{{- if or .HasImport .HasImportIDConfig .HasImportIdentityConfig }}

## Import

Import is supported using the following syntax:
{{- end }}
{{- if .HasImportIdentityConfig }}

In Terraform v1.12.0 and later, the [` + "`" + `import` + "`" + ` block](https://developer.hashicorp.com/terraform/language/import) can be used with the ` + "`" + `identity` + "`" + ` attribute, for example:

{{tffile .ImportIdentityConfigFile }}

{{ .IdentitySchemaMarkdown | trimspace }}
{{- end }}
{{- if .HasImportIDConfig }}

In Terraform v1.5.0 and later, the [` + "`" + `import` + "`" + ` block](https://developer.hashicorp.com/terraform/language/import) can be used with the ` + "`" + `id` + "`" + ` attribute, for example:

{{tffile .ImportIDConfigFile }}
{{- end }}
{{- if .HasImport }}

The [` + "`" + `terraform import` + "`" + ` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:

{{codefile "shell" .ImportFile }}
{{- end }}
`

const defaultFunctionTemplate functionTemplate = `---
` + frontmatterComment + `
page_title: "{{.Name}} {{.Type}} - {{.RenderedProviderName}}"
subcategory: ""
description: |-
{{ .Summary | plainmarkdown | trimspace | prefixlines "  " }}
---

# {{.Type}}: {{.Name}}

{{ .Description | trimspace }}

{{ if .HasExamples -}}
## Example Usage

{{- range .ExampleFiles }}

{{ tffile . }}
{{- end }}
{{- end }}

## Signature

{{ .FunctionSignatureMarkdown }}

## Arguments

{{ .FunctionArgumentsMarkdown }}
{{- if .HasVariadic }}
{{ .FunctionVariadicArgumentMarkdown }}
{{- end }}
`

const defaultProviderTemplate providerTemplate = `---
` + frontmatterComment + `
page_title: "{{.ProviderShortName}} Provider"
description: |-
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
---

# {{.ProviderShortName}} Provider

{{ .Description | trimspace }}

{{ if .HasExamples -}}
## Example Usage

{{- range .ExampleFiles }}

{{ tffile . }}
{{- end }}
{{- end }}

{{ .SchemaMarkdown | trimspace }}
`

const migrateProviderTemplateComment string = `
{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates.

For example, the {{ .SchemaMarkdown }} template can be used to replace manual schema documentation if descriptions of schema attributes are added in the provider source code. */ -}}
`

const migrateFunctionTemplateComment string = `
{{/* This template serves as a starting point for documentation generation, and can be customized with hardcoded values and/or doc gen templates.

For example, the {{ .FunctionArgumentsMarkdown }} template can be used to replace manual argument documentation if descriptions of function arguments are added in the provider source code. */ -}}
`