hashicorp / hashicorp/terraform-plugin-docs

Ability to customize the `.SchemaMarkdown`

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

Description

### 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**.

```bash
$ 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

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.