Allow setting subcategory from code

[fbreckle]

Hi,

per the docs, subcategories can be used to add some structure to the docs.
The default template defaults to "", which I could then manually adjust.

The problem with this is this: I maintain a provider with many external contributions are via pull requests. We have a pipeline that enforces that the documentation is updated by running tfplugindocs on the PR and then erroring if there are any changes. This means the author of the PR themselves must run tfplugindocs if they introduce a new attribute or resource to update the docs in their PR.

This means managing the subcategory manually is not an option.

[kwent]

How can we help support this feature ?

[fbreckle]

I actually recently implemented this in a fork of this repo at https://github.com/fbreckle/terraform-plugin-docs
In that fork, you can add metadata to the description attribute, which will then set the subcategory in the template. The metadata will then be stripped when creating the documentation.
You can see this implemented in e-breuninger/terraform-provider-netbox@1d1196a#diff-298869f21140588fa6fe0a0810d47e429d22d189e570606afb73ea7f2905d293

I find this approach invasive enough that I did not make a PR in in this repo, though if the maintainers of this repo are interested, I can surely create a merge request.

[austinvalle]

Hi all! 👋🏻

Thanks for creating this issue and sorry about the delayed response. We don't have a clear path for solving this issue yet and I'll try to give more context as to why.

The current terraform-plugin-docs tool is dependent on using Terraform CLI's terraform providers schema -json output. This dependency restricts us in what we can easily change to provide richer documentation for providers today (such as the subcategory mapping), as we can only utilize Description and MarkdownDescrption. To reference another similar request that has a more detailed answer here, our next step is to move away from this dependency by providing richer schema information directly from the provider itself (that format/process is still TBD, but the implementation would be in the new terraform-plugin-framework).

Apologies that this might not be the answer you're looking for, but hopefully it gives you useful context into how we're planning on approaching the problem.

[fbreckle]

Hi,

thanks for your response! Actually, my fork is working quite fine for the time being. As long as there is some awareness for this issue, I'm fine.

I thought a solution would be to add a meta attribute of type map[string]string to schema.Schema where plugin authors can just dump arbitrary information. Then, terraform-plugin-docs could just parse e.g. the meta["terraform-plugin-docs"]string in addition to thePlaintextstring. Maybe even make it a map in a map, so we could setmeta["terraform-plugin-docs"]["subcategory"] = XYZ. terraform-plugin-docs` would then just read those keys and do its thing.

That said, I really did not put too much tought into this :D and also I did not yet get to use the framework, I still use the SDKv2. Just my two cents, I guess. I will see what you guys come up with.

[b-per]

In case it helps anyone still having this issue, my workaround is to update the template resources.md.tmpl to be the following:

---
page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
{{ if gt (len (split .Description " --- ")) 1 -}}
subcategory: "{{ index (split .Description " --- ") 0 }}"
{{- else -}} 
subcategory: ""
{{- end }}
description: |-
{{ if gt (len (split .Description " --- ")) 1 -}}
{{ index (split .Description " --- ") 1 | plainmarkdown | trimspace | prefixlines "  " }}
{{- else -}} 
{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
{{- end }}
---

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

{{ if gt (len (split .Description " --- ")) 1 -}}
{{ index (split .Description " --- ") 1 | trimspace }}
{{ else }}
{{ .Description | trimspace }}
{{- end }}

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

{{ tffile (printf "%s%s%s" "examples/resources/" .Name "/resource.tf") }}
{{- end }}

{{ .SchemaMarkdown | trimspace }}
{{- if .HasImport }}

## Import

Import is supported using the following syntax:

{{ codefile "shell" (printf "%s%s%s" "examples/resources/" .Name "/import.sh") }}
{{- end }}

This allows me to define resources descriptions with My Subcategory --- The description of my resource and have the Subcategory and Description correctly filled in. It also works if people don't provide a Subcategory, in that case, it will just populate the Description.

The only caveat is that People can't write --- in their description (or if you do, change this string to one that you will never write in your desc).