Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support Provider-Defined Function Documentation #307

Closed
bflad opened this issue Dec 14, 2023 · 3 comments · Fixed by #328
Closed

Support Provider-Defined Function Documentation #307

bflad opened this issue Dec 14, 2023 · 3 comments · Fixed by #328
Labels
enhancement New feature or request
Milestone

Comments

@bflad
Copy link
Contributor

bflad commented Dec 14, 2023

Background

Terraform 1.8 will be introducing provider-defined function support and the public Terraform Registry will support the ingress and display of provider-defined function documentation. Both parts of this feature are under active development, so this issue description may change slightly to match implementation details.

For extracting machine-readable function information from providers, the existing terraform providers schema -json command output will be updated to include the following:

{
  "format_version": "VERSION",
  "provider_schemas": {
    "PROVIDER_ADDRESS": {
      // ... existing properties ...
      "functions": {
        "format_version": "...",
        "function_signatures": {
          "FUNCTION_NAME": {
            "summary": "...", // short description
            "description": "...", // long description
            "deprecation_message": "...",
            "parameters": [
              {
                "description": "...",
                "name": "...", // display name, e.g. for function signature form
                "type": "..."
              }
            ],
            "result_type": "...",
            "variadic_parameter": {
              "description": "...",
              "name": "...", // display name, e.g. for function signature form
              "type": "..."
            }
          }
        }
      }
    }
  }
}

For ingress and display of this documentation, the public Terraform Registry expects Markdown source files in conventional file locations similar to existing managed resource and data source files. From the base directory of a provider codebase: docs/functions/NAME.md.

Proposal

Update the migrate command to automatically handle migrating website/docs/functions/NAME.* files.

Update the generate command to automatically generate provider-defined function documentation, similar to managed resource and data source documentation. Function documentation should support custom templates and those templates should support existing template functions.

The proposed conventional function documentation content is as follows:

---
page_title: contains_ip Function - terraform-provider-cidr
description: |-
  Returns a boolean whether a RFC4632 CIDR contains an IP address.
---

# Function: contains_ip

Returns a boolean whether a RFC4632 CIDR contains an IP address.

## Example Usage

```terraform
# result: true
provider::cidr::contains_ip("10.0.0.0/8", "10.0.0.1")
```

## Signature

```text
contains_ip(cidr string, ip string) bool
```

## Arguments

1. `cidr` (String) RFC4632 CIDR to check whether it contains the given IP address.
2. `ip` (String) IP address to check whether its contained in the RFC4632 CIDR.

So a default template may look like the following:

---
page_title: "{{.Name}} Function - {{ .ProviderName }}"
subcategory: ""
description: |-
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
---

# Function: {{.Name}}

{{ .Description | trimspace }}

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

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

## Signature

{{ .FunctionSignatureMarkdown }}

## Arguments

{{ .FunctionArgumentsMarkdown }}

Where the new FunctionSignatureMarkdown and FunctionArgumentsMarkdown template functions handle the business of looping through the parameters, variadic parameter, and return.

@bflad bflad added the enhancement New feature or request label Dec 14, 2023
@bflad
Copy link
Contributor Author

bflad commented Jan 5, 2024

Initial Terraform implementation: hashicorp/terraform#34450

@bflad
Copy link
Contributor Author

bflad commented Jan 8, 2024

Created hashicorp/terraform-json#118 for tracking terraform-json updates necessary.

Copy link

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators May 23, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant