-
Notifications
You must be signed in to change notification settings - Fork 44
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Get extra nested docs from schema map (#1650)
This pull request aims to improve accuracy for nested property docs descriptions. It uses the SchemaMap to look up and read `Description` fields [such as this one](https://github.com/kreuzwerker/terraform-provider-docker/blob/master/internal/provider/provider.go#L111) in the case where trying to obtain documentation form `entityDocs` does not yield any results. The original impetus for this change was to address #1045, which is very specific to Config() fields. The Provider configuration docs are special-cased in the bridge and we do not have access to any `entityDocs`. Instead, we were reading in the TF schema's Description() field into `rawdocs` when generating a top-level config variable. This did not persist into any nested fields on Configuration variables, hence this fix. But it turns out that we can catch quite a few more missing descriptions if we extend implementation across all nested fields (see stats below). As a side note - the Terraform Plugin Framework implements `Description()` in a way that respects and prioritizes descriptions that come from Markdown docs; for `sdkv2` resources we still need to use, and prefer, our parsed-from-markdown `entityDocs` descriptions. It would be interesting to see if we get improved docs for TFPF resources by not reading descriptions from `entityDocs`. It was also necessary to return an empty string from TFPF `typeSchema` so as not to cause a panic during schemagen on TFPF using providers. Open to improvements/suggestions here! This PR aims to be fully additive - we are not changing the way in which docs are generated; we only fill in missing docs. Nevertheless, this PR does also seem to improve the correctness of nested docs where some description fields have been matched to the wrong input field. Please see a [new Docker schema generated against these changes](https://github.com/pulumi/pulumi-docker/blob/nested-configs-sample-schema/provider/cmd/pulumi-resource-docker/schema.json) Quick stats: ``` pulumi/pulumi-docker🦉 git diff master --stat -- provider/cmd provider/cmd/pulumi-resource-docker/schema.json | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------ 1 file changed, 68 insertions(+), 43 deletions(-) ``` Here is [an AWS schema](https://github.com/pulumi/pulumi-aws/blob/testing-docsgen/provider/cmd/pulumi-resource-aws/schema.json) - you will want to pull that branch and look at the git diff to `master` locally. Quick stats: ``` pulumi/pulumi-aws🦉 git diff master --stat -- provider/cmd provider/cmd/pulumi-resource-aws/schema.json | 1810 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------ 1 file changed, 1206 insertions(+), 604 deletions(-) ``` This PR fixes #1045.
- Loading branch information
Showing
13 changed files
with
441 additions
and
94 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,92 @@ | ||
| // Copyright 2016-2022, Pulumi Corporation. | ||
| // | ||
| // Licensed under the Apache License, Version 2.0 (the "License"); | ||
| // you may not use this file except in compliance with the License. | ||
| // You may obtain a copy of the License at | ||
| // | ||
| // http://www.apache.org/licenses/LICENSE-2.0 | ||
| // | ||
| // Unless required by applicable law or agreed to in writing, software | ||
| // distributed under the License is distributed on an "AS IS" BASIS, | ||
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| // See the License for the specific language governing permissions and | ||
| // limitations under the License. | ||
|
|
||
| package testprovider | ||
|
|
||
| import ( | ||
| "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema" | ||
| ) | ||
|
|
||
| // Subset of pulumi-cloudflare provider. | ||
| func ProviderNestedDescriptions() *schema.Provider { | ||
| resourceRuleset := func() *schema.Resource { | ||
| return &schema.Resource{ | ||
| Description: "Deploy a ruleset for cloudflare", | ||
| Schema: resourceNestedDescriptionsSchema(), | ||
| } | ||
| } | ||
|
|
||
| return &schema.Provider{ | ||
| Schema: map[string]*schema.Schema{}, | ||
| ResourcesMap: map[string]*schema.Resource{ | ||
| "cloudflare_ruleset": resourceRuleset(), | ||
| }, | ||
| } | ||
| } | ||
|
|
||
| // An aggressively cut down version of cloudflare_ruleset. | ||
| func resourceNestedDescriptionsSchema() map[string]*schema.Schema { | ||
| return map[string]*schema.Schema{ | ||
| "name": { | ||
| Type: schema.TypeString, | ||
| Required: true, | ||
| ForceNew: true, | ||
| Description: "Name of the ruleset.", | ||
| }, | ||
| "description": { | ||
| Type: schema.TypeString, | ||
| Optional: true, | ||
| Description: "Brief summary of the ruleset and its intended use.", | ||
| }, | ||
| "rules": { | ||
| Type: schema.TypeList, | ||
| Optional: true, | ||
| Description: "List of rules to apply to the ruleset.", | ||
| Elem: &schema.Resource{ | ||
| Schema: map[string]*schema.Schema{ | ||
| "id": { | ||
| Type: schema.TypeString, | ||
| Computed: true, | ||
| Description: "Unique rule identifier.", | ||
| }, | ||
| "version": { | ||
| Type: schema.TypeString, | ||
| Computed: true, | ||
| Description: "Version of the ruleset to deploy.", | ||
| }, | ||
| "action_parameters": { | ||
| Type: schema.TypeList, | ||
| Optional: true, | ||
| Description: "List of parameters that configure the behavior of the ruleset rule action.", | ||
| Elem: &schema.Resource{ | ||
| Schema: map[string]*schema.Schema{ | ||
| "id": { | ||
| Type: schema.TypeString, | ||
| Optional: true, | ||
| Description: "Identifier of the action parameter to modify. " + | ||
| "When Terraform is mentioned here, the description should be dropped.", | ||
| }, | ||
| "translateField": { | ||
| Type: schema.TypeString, | ||
| Optional: true, | ||
| Description: "When cloudflare_ruleset is mentioned, it should be translated.", | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| }, | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.