Documentation ¶
Overview ¶
Facilities to help caching the example generation. Generating examples is expensive, especially when using the convert_cli.go method that interacts with an external process. Typically provider builds first generate the schema, and then generate concrete language SDKs for Python, TypeScript and so on; these processes start from scratch as they do not easily decompose into passes, and naively they perform the conversion work multiple times. Using a file-based cache speeds up the process by avoiding repeat conversion.
Pulling out some of the repeated strings tokens into constants would harm readability, so we just ignore the goconst linter's warning.
Index ¶
- Constants
- Variables
- func GenerateSchema(info tfbridge.ProviderInfo, sink diag.Sink) (pschema.PackageSpec, error)
- func LoadGoMod() (*modfile.File, error)
- func Main(pkg string, version string, prov tfbridge.ProviderInfo)
- func MainWithCustomGenerate(pkg string, version string, prov tfbridge.ProviderInfo, ...)
- func SkipSectionByHeaderContent(content []byte, shouldSkipHeader func(headerText string) bool) ([]byte, error)
- type ConversionError
- type CoverageTracker
- type DocFile
- type DocKind
- type DocsSource
- type DocumentationPage
- type Example
- type GenerateOptions
- type GenerateSchemaOptions
- type GenerateSchemaResult
- type Generator
- type GeneratorOptions
- type GetRepoPathErr
- type Language
- type LanguageConversionResult
Constants ¶
const ( Success = 0 Warning = 1 Failure = 2 Fatal = 3 )
Conversion outcome severity values
Variables ¶
Functions ¶
func GenerateSchema ¶
func GenerateSchema(info tfbridge.ProviderInfo, sink diag.Sink) (pschema.PackageSpec, error)
func Main ¶
func Main(pkg string, version string, prov tfbridge.ProviderInfo)
Main executes the TFGen process for the given package pkg and provider prov.
func MainWithCustomGenerate ¶ added in v3.34.0
func MainWithCustomGenerate(pkg string, version string, prov tfbridge.ProviderInfo, gen func(GeneratorOptions) error)
Like Main but allows to customize the generation logic past the parsing of cmd-line arguments.
func SkipSectionByHeaderContent ¶ added in v3.89.1
func SkipSectionByHeaderContent( content []byte, shouldSkipHeader func(headerText string) bool, ) ([]byte, error)
SkipSectionByHeaderContent removes headers where shouldSkipHeader(header) returns true, along with any text under the header. content is assumed to be Github flavored markdown when parsing.
shouldSkipHeader is called on the raw header text, like this:
shouldSkipHeader("My Header")
*not* like this:
// This is wrong shouldSkipHeader("## My Header\n")
Example of removing the first header and its context
result := SkipSectionByHeaderContent(byte[]( ` ## First Header First content ## Second Header Second content `, func(headerText string) bool) ([]byte, error) { return headerText == "First Header" })
The result will only now contain the second result:
## Second Header Second content
Types ¶
type ConversionError ¶ added in v3.34.0
type ConversionError struct {
// contains filtered or unexported fields
}
A ConversionError occurs when convert.Convert yields a panic. This can be removed when https://github.com/pulumi/pulumi-terraform-bridge/issues/477 is resolved. ConversionError exposes the stacktrace of the panic so callers can choose to pass the trace along to the user or swallow it.
func (*ConversionError) Error ¶ added in v3.34.0
func (err *ConversionError) Error() string
Return the err-representation of this struct.
func (*ConversionError) StackTrace ¶ added in v3.34.0
func (err *ConversionError) StackTrace() string
StackTrace returns the stacktrace of the error.
func (*ConversionError) Unwrap ¶ added in v3.34.0
func (err *ConversionError) Unwrap() error
Unwrap provides error as returned by the conversion panic.
type CoverageTracker ¶ added in v3.6.0
type CoverageTracker struct { ProviderName string // Name of the provider ProviderVersion string // Version of the provider EncounteredPages map[string]*DocumentationPage // Map linking page IDs to their data }
Main overarching structure for storing coverage data on how many examples were processed, how many failed, and for what reason. At different stages, the code translator notifies the tracker of what is going on. Notifications are treated as an ordered sequence of events.
NOTIFICATION INTERFACE:
example := getOrCreateExample(pageName, hcl)
languageConversionSuccess(example, targetLanguage)
languageConversionWarning(example, targetLanguage, warningDiagnostics)
languageConversionFailure(example, targetLanguage, failureDiagnostics)
languageConversionPanic(example, targetLanguage, panicInfo)
type DocKind ¶
type DocKind string
DocKind indicates what kind of entity's documentation is being requested.
const ( // ResourceDocs indicates documentation pertaining to resource entities. ResourceDocs DocKind = "resources" // DataSourceDocs indicates documentation pertaining to data source entities. DataSourceDocs DocKind = "data-sources" // InstallationDocs indicates documentation pertaining to provider configuration and installation. InstallationDocs DocKind = "installation" )
type DocsSource ¶ added in v3.61.0
type DocsSource interface {
// contains filtered or unexported methods
}
A source of documentation bytes.
func NewGitRepoDocsSource ¶ added in v3.61.0
func NewGitRepoDocsSource(g *Generator) DocsSource
type DocumentationPage ¶ added in v3.12.0
type DocumentationPage struct { Name string // The unique ID of this documentation page Examples []Example // This page's examples, stored in the order they were found }
A structure encompassing a single page, which contains one or more examples. This closely resembles the web pages seen in Pulumi/Terraform documentation.
type Example ¶ added in v3.12.0
type Example struct { OriginalHCL string // Original HCL code that the example was found with ConversionResults map[string]*LanguageConversionResult // Mapping language names to their conversion results }
Contains information about a single example, consisting of a block of HCL and one or more language conversion results.
type GenerateOptions ¶
type GenerateOptions struct {
ModuleFormat string
}
type GenerateSchemaOptions ¶ added in v3.34.0
type GenerateSchemaOptions struct { ProviderInfo tfbridge.ProviderInfo DiagnosticsSink diag.Sink XInMemoryDocs bool }
type GenerateSchemaResult ¶ added in v3.34.0
type GenerateSchemaResult struct {
PackageSpec pschema.PackageSpec
}
func GenerateSchemaWithOptions ¶ added in v3.34.0
func GenerateSchemaWithOptions(opts GenerateSchemaOptions) (*GenerateSchemaResult, error)
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
func NewGenerator ¶
func NewGenerator(opts GeneratorOptions) (*Generator, error)
NewGenerator returns a code-generator for the given language runtime and package info.
func (*Generator) Generate ¶
Generate creates Pulumi packages from the information it was initialized with.
func (*Generator) UnstableGenerateFromSchema ¶ added in v3.44.0
func (g *Generator) UnstableGenerateFromSchema(genSchemaResult *GenerateSchemaResult) error
GenerateFromSchema creates Pulumi packages from a pulumi schema and the information the generator was initialized with.
This is an unstable API. We have exposed it so other packages within pulumi-terraform-bridge can consume it. We do not recommend other packages consume this API.
type GeneratorOptions ¶
type GeneratorOptions struct { Package string Version string Language Language ProviderInfo tfbridge.ProviderInfo Root afero.Fs ProviderInfoSource il.ProviderInfoSource PluginHost plugin.Host TerraformVersion string Sink diag.Sink Debug bool SkipDocs bool SkipExamples bool CoverageTracker *CoverageTracker // XInMemoryDocs instructs the generator not to attempt to find a repository to // draw docs from, relying only on TF schema level docs. // // XInMemoryDocs is an experimental feature, and does not have any backwards // compatibility guarantees. XInMemoryDocs bool }
type GetRepoPathErr ¶ added in v3.61.0
An error that represents a missing repo path directory.
func (GetRepoPathErr) Error ¶ added in v3.61.0
func (e GetRepoPathErr) Error() string
func (GetRepoPathErr) Unwrap ¶ added in v3.61.0
func (e GetRepoPathErr) Unwrap() error
type Language ¶
type Language string
const ( Golang Language = "go" NodeJS Language = "nodejs" Python Language = "python" CSharp Language = "dotnet" Schema Language = "schema" PCL Language = "pulumi" // RegistryDocs // Setting RegistryDocs as a separate bridge "language" in the bridge allows us to create custom logic specific to // transforming and emitting upstream installation docs. // When we generate registry docs, we want to: //- be able to generate them via a separate command so we can enable it on a per-provider basis //- be able to pass a separate output location from the schema location (in this case, `docs/`) //- convert examples into all Pulumi-supported languages RegistryDocs Language = "registry-docs" )
type LanguageConversionResult ¶ added in v3.6.0
type LanguageConversionResult struct { FailureSeverity int // This conversion's outcome: [Success, Warning, Failure, Fatal] FailureInfo string // Additional in-depth information Program string // Converted program // How many times this example has been converted to this language. // It is expected that this will be equal to 1. TranslationCount int }
Individual language information concerning how successfully an example was converted to Pulumi
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
internal
|
|
autofill
Package autofill implements filling undeclared references in examples.
|
Package autofill implements filling undeclared references in examples. |
section
package section provides an extension to goldmark: a section.
|
package section provides an extension to goldmark: a section. |