hashicorp / hashicorp/terraform-plugin-docs
Ability to customize the `.SchemaMarkdown`
- 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.