hashicorp / hashicorp/terraform-plugin-docs

Attributes with multiple line Markdown descriptions are not aligned with list item

Open
#531 2 comments 0 reactions 0 assignees View on GitHub
bug contributions-welcome
Dominant language
Go
Stars
263
Forks
84
Avg merge
3d 6h
Merged PRs (30d)
2

Description

### Terraform CLI and terraform-plugin-docs Versions

Latest Terraform version (1.13.5).

```
github.com/hashicorp/terraform-plugin-docs v0.22.0
```

### Provider Code

```go
func (r *APIDocumentResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
resp.Schema = schema.Schema{
MarkdownDescription: "APIDocument Resource",
Attributes: map[string]schema.Attribute{
// ...
"parent_document_id": schema.StringAttribute{
Optional: true,
MarkdownDescription: `API Documents may be rendered as a tree of files.` + "\n" +
`` + "\n" +
`Specify the ` + "`" + `id` + "`" + ` of another API Document as the ` + "`" + `parent_document_id` + "`" + ` to add some heirarchy do your documents.`,
},
```

### Expected Behavior

Given that `terraform-plugin-docs` is writing the attribute as a Markdown list item, multiple line text should be aligned with the line item automatically.

### Actual Behavior

Additional lines of attribute descriptions are left-aligned (not indented) so the schema attribute list gets broken up into list items with bullets and padded left-aligned paragraphs. Especially with lengthy descriptions (e.g. with multiple paragraphs), its harder for practitioners to read.

One more trivial real world example:

Image

Ideally, the schema markdown rendering of `terraform-plugin-docs` has context that its being written into a list with list item syntax and therefore should align the full description with the list item.

Its worth mentioning that these descriptions are being sourced from OpenAPI Specification documents, where the description may be used for other purposes and its difficult for API producers to know/understand tool-specific intricacies. A potential workaround is manually injecting space indentation characters into the Markdown description after multiple newline characters, however this may cause other tooling also using that description to be formatted unexpectedly.

### Steps to Reproduce

Create any schema attribute `MarkdownDescription` with multiple, sequential newline characters.

### How much impact is this issue causing?

Low

### Logs

_No response_

### Additional Information

_No response_

### Code of Conduct

- [x] I agree to follow this project's Code of Conduct

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.