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  }