github.com/myhau/pulumi/pkg/v3@v3.70.2-0.20221116134521-f2775972e587/codegen/docs.go (about) 1 // Copyright 2016-2020, Pulumi Corporation. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 package codegen 16 17 import ( 18 "github.com/pgavlin/goldmark/ast" 19 20 "github.com/pulumi/pulumi/pkg/v3/codegen/schema" 21 ) 22 23 // DocLanguageHelper is an interface for extracting language-specific information from a Pulumi schema. 24 // See the implementation for this interface under each of the language code generators. 25 type DocLanguageHelper interface { 26 GetPropertyName(p *schema.Property) (string, error) 27 GetEnumName(e *schema.Enum, typeName string) (string, error) 28 GetDocLinkForResourceType(pkg *schema.Package, moduleName, typeName string) string 29 GetDocLinkForPulumiType(pkg *schema.Package, typeName string) string 30 GetDocLinkForResourceInputOrOutputType(pkg *schema.Package, moduleName, typeName string, input bool) string 31 GetDocLinkForFunctionInputOrOutputType(pkg *schema.Package, moduleName, typeName string, input bool) string 32 GetLanguageTypeString(pkg *schema.Package, moduleName string, t schema.Type, input bool) string 33 34 GetFunctionName(modName string, f *schema.Function) string 35 // GetResourceFunctionResultName returns the name of the result type when a static resource function is used to lookup 36 // an existing resource. 37 GetResourceFunctionResultName(modName string, f *schema.Function) string 38 39 GetMethodName(m *schema.Method) string 40 GetMethodResultName(pkg *schema.Package, modName string, r *schema.Resource, m *schema.Method) string 41 42 // GetModuleDocLink returns the display name and the link for a module (including root modules) in a given package. 43 GetModuleDocLink(pkg *schema.Package, modName string) (string, string) 44 } 45 46 func filterExamples(source []byte, node ast.Node, lang string) { 47 var c, next ast.Node 48 for c = node.FirstChild(); c != nil; c = next { 49 filterExamples(source, c, lang) 50 51 next = c.NextSibling() 52 switch c := c.(type) { 53 case *ast.FencedCodeBlock: 54 sourceLang := string(c.Language(source)) 55 if sourceLang != lang && sourceLang != "sh" { 56 node.RemoveChild(node, c) 57 } 58 case *schema.Shortcode: 59 switch string(c.Name) { 60 case schema.ExampleShortcode: 61 hasCode := false 62 for gc := c.FirstChild(); gc != nil; gc = gc.NextSibling() { 63 if gc.Kind() == ast.KindFencedCodeBlock { 64 hasCode = true 65 break 66 } 67 } 68 if hasCode { 69 var grandchild, nextGrandchild ast.Node 70 for grandchild = c.FirstChild(); grandchild != nil; grandchild = nextGrandchild { 71 nextGrandchild = grandchild.NextSibling() 72 node.InsertBefore(node, c, grandchild) 73 } 74 } 75 node.RemoveChild(node, c) 76 case schema.ExamplesShortcode: 77 if first := c.FirstChild(); first != nil { 78 first.SetBlankPreviousLines(c.HasBlankPreviousLines()) 79 } 80 81 var grandchild, nextGrandchild ast.Node 82 for grandchild = c.FirstChild(); grandchild != nil; grandchild = nextGrandchild { 83 nextGrandchild = grandchild.NextSibling() 84 node.InsertBefore(node, c, grandchild) 85 } 86 node.RemoveChild(node, c) 87 } 88 } 89 } 90 } 91 92 // FilterExamples filters the code snippets in a schema docstring to include only those that target the given language. 93 func FilterExamples(description string, lang string) string { 94 if description == "" { 95 return "" 96 } 97 98 source := []byte(description) 99 parsed := schema.ParseDocs(source) 100 filterExamples(source, parsed, lang) 101 return schema.RenderDocsToString(source, parsed) 102 }