Render Resource Description in Markdown

[deepbrook]

What problem are you facing?

When rendering documentation as - for example - JSON, each resource has a description attribute present, which is populated by the preceding comment above the block in the config:

$ cat group.tf
// This comment shows up in JSON output
resource "ldap_group" "this" {...}
$ terraform-docs json .
...
  "resources": [
    {
      "type": "group",
      "name": "this",
      "provider": "ldap",
      "source": "Ouest-France/ldap",
      "mode": "managed",
      "version": "latest",
      "description": "This comment shows up in JSON output"
    },

However, when running the markdown command, the description doesn't show :<

$ terraform-docs md .

| Name | Type |
|------|------|
| [ldap_group.this](https://registry.terraform.io/providers/Ouest-France/ldap/latest/docs/resources/group) | resource |

How could terraform-docs help solve your problem?

it'd be really cool if descriptions would be rendered in md mode as well, like so:

$ terraform-docs md .

| Name | Type | Description|
|------|------|
| [ldap_group.this](https://registry.terraform.io/providers/Ouest-France/ldap/latest/docs/resources/group) | resource | This comment shows up in JSON output |

[derekmurawsky]

This would be invaluable from a clarity of intent perspective.

[jason-johnson]

Can this be done via .Module.Resources? I see Resource has a Description field.

[amentee]

@derekmurawsky - Is this feature implemented ?

[amentee]

@deepbrook - did you solved this issue?

I used below .terraform-docs.yml. It only shows description column with some content if I put that as a comment, but if I put it in description parameter it does not take. Its strange. Can some explain this behaviour

formatter: "markdown" # this is required

version: ""

recursive:
  enabled: false
  path: modules

sections:
  hide: []
  show: []

content: |-
  | Name | Type | Description |
  |------|------|-------------|
  {{- range .Module.Resources }}
    {{- $isResource := and $.Config.Sections.Resources (eq "resource" (printf "%s" .GetMode)) }}
    {{- $isDataResource := and $.Config.Sections.DataSources (eq "data source" (printf "%s" .GetMode)) }}
    {{- if or $isResource $isDataResource }}
      {{- $fullspec := ternary .URL (printf "[%s](%s)" .Spec .URL) .Spec }}
      {{ $fullspec }} | {{ .GetMode }} | {{  tostring .Description | sanitizeMarkdownTbl   }} | 
    {{- end }}
  {{- end }}

output:
  file: "K3s.md"
  mode: inject
  template: |-
    <!-- BEGIN_TF_DOCS -->
    {{ .Content }}
    <!-- END_TF_DOCS -->

output-values:
  enabled: false
  from: ""

sort:
  enabled: true
  by: name

settings:
  anchor: true
  color: true
  default: true
  description: true 
  escape: true
  hide-empty: false
  html: true
  indent: 2
  lockfile: true
  read-comments: true 
  required: true
  sensitive: true
  type: true

Below is the resource block

  //This is security group for k3 server nodes
resource "aws_security_group" "k3_server_nodes" {
    name  = "${var.prefix}-k3-server-nodes"
    description = "This is security group for k3 server nodes"
    vpc_id = var.vpc_id
}

aws_security_group.k3_server_nodes resource Create security group for k3s server nodes

[lenox-joseph]

I'm seeing the same for resources on 0.19.0 -- any resource with a description block does not get rendered at all with a content block that calls out .Description. It won't get rendered ever without overriding the content block.

Additionally, any text is flattened down to one line, which is super frustrating when trying to make comments/descriptions that are useful both extracted in-place (most of my comments are discussing usage of local_file templates or related.

content: |-
  {{- range .Module.Resources }}
    {{- $isResource := and $.Config.Sections.Resources (eq "resource" (printf "%s" .GetMode)) }}
    {{- $isDataResource := and $.Config.Sections.DataSources (eq "data source" (printf "%s" .GetMode)) }}
    {{- if or $isResource $isDataResource }}
      {{- $fullspec := ternary .URL (printf "[%s](%s)" .Spec .URL) .Spec }}
  - {{ $fullspec }}
      - `{{ .Position.Filename }}*{{ .Position.Line }}`
      - {{  tostring .Description }}
    {{- end }}
  {{- end }}

// this will get rendered
// but all the text will be 
// jammed into one line
resource "local_file" "resourcename" {
}

# this will get rendered
# but all the text will be 
# jammed into one line
resource "local_file" "resourcename" {
}

/* this will
* not get rendered
*/
resource "local_file" "resourcename" {
}

resource "local_file" "resourcename" {
    description = "this will not get rendered"
}