terraform-plugin-docs icon indicating copy to clipboard operation
terraform-plugin-docs copied to clipboard
verified publisher icon hashicorp

Ability to customize the `.SchemaMarkdown`

Open mkilchhofer opened this issue 8 months ago • 4 comments

Terraform CLI and terraform-plugin-docs Versions

v0.21.0

Use Cases or Problem Statement

With other colleagues I maintain the TF provider to provision Applications inside Argo CD: https://github.com/argoproj-labs/terraform-provider-argocd

We have a very "big"/complex resource with a matrix generator: https://github.com/argoproj-labs/terraform-provider-argocd/blob/main/docs/resources/application_set.md

Our "main" issue is that the size of this file is 1.3MiB and therefore 300KiB over the registry limit for a markdown file.

Specifically speaking, the same data structure appears on multiple levels inside the resource:

"metadata" (annotations, labels, name, namespace, finalizers)

### Nested Schema for `spec.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.git.template.metadata`
### Nested Schema for `spec.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.git.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.git.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.matrix.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.git.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.list.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.merge.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.matrix.template.metadata`
### Nested Schema for `spec.generator.merge.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.merge.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.merge.generator.git.template.metadata`
### Nested Schema for `spec.generator.merge.generator.list.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.git.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.list.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.merge.generator.matrix.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.cluster_decision_resource.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.clusters.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.git.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.list.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.merge.generator.merge.template.metadata`
### Nested Schema for `spec.generator.merge.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.merge.generator.pull_request.template.metadata`
### Nested Schema for `spec.generator.merge.generator.scm_provider.template.metadata`
### Nested Schema for `spec.generator.merge.template.metadata`
### Nested Schema for `spec.generator.plugin.template.metadata`
### Nested Schema for `spec.generator.pull_request.template.metadata`

"secret reference" (key, secret_name)

### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.matrix.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.merge.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.matrix.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.matrix.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.merge.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.merge.generator.scm_provider.gitlab.token_ref`
### Nested Schema for `spec.generator.pull_request.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.pull_request.gitea.token_ref`
### Nested Schema for `spec.generator.pull_request.github.token_ref`
### Nested Schema for `spec.generator.pull_request.gitlab.token_ref`
### Nested Schema for `spec.generator.scm_provider.azure_devops.access_token_ref`
### Nested Schema for `spec.generator.scm_provider.bitbucket_cloud.app_password_ref`
### Nested Schema for `spec.generator.scm_provider.bitbucket_server.basic_auth.password_ref`
### Nested Schema for `spec.generator.scm_provider.gitea.token_ref`
### Nested Schema for `spec.generator.scm_provider.github.token_ref`
### Nested Schema for `spec.generator.scm_provider.gitlab.token_ref`

I count all nested schemas for this particular resource, we see 1645.

$ cat docs/resources/application_set.md  | grep 'Nested Schema for' | wc --lines
1645

Proposal

A way to define the structure once (I'd be okay to define those manually) and reference from all links to exactly this one structure.

How much impact is this issue causing?

Medium

Additional Information

No response

Code of Conduct

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

Xref (to issue in TF provider repo):

  • https://github.com/argoproj-labs/terraform-provider-argocd/issues/527

mkilchhofer avatar May 15 '25 14:05 mkilchhofer

any update?

AkakievKD avatar Jul 15 '25 15:07 AkakievKD

Needs attention. Maybe @austinvalle ?

mkilchhofer avatar Sep 22 '25 13:09 mkilchhofer

Hi @mkilchhofer thanks for raising this issue.

This is a problem we have seen in the past so we are open to different solutions/contributions for addressing it. To make sure we are understanding the ask, is the proposal asking for a way to toggle parts of the markdown to be not generated so that they may filled in manually? Or are you are you proposing a way for the markdown to reference a nested schema that already has been defined in place of having it repeat in order to save space?

rainkwan avatar Nov 13 '25 17:11 rainkwan

@rainkwan

I am completely fine with either solution. 👍

mkilchhofer avatar Nov 20 '25 17:11 mkilchhofer