pulumi/pkg/codegen/docs/templates/function.tmpl

132 lines
5.2 KiB
Cheetah
Raw Normal View History

{{ template "header" .Header }}
{{ htmlSafe "<!-- WARNING: this file was generated by" }} {{ .Tool }}. {{ htmlSafe "-->" }}
{{ htmlSafe "<!-- Do not edit by hand unless you're certain you know what you are doing! -->" }}
{{- if .DeprecationMessage }}
[docsgen] Fix rendering of deprecated messages and text in description lists (#13773) A change was made a while back to remove the use of shortcodes. As part of that, the shortcode used to render markdown was replaced by a function call that used goldmark to render markdown. The resulting HTML from that wraps the text in paragraph tags. This causes some problems for rendering the docs. For deprecations, the deprecation message now shows up outside of the "Deprecated" box. This happens because the rendered markdown was being wrapped in `<p></p>` tags, leading to `<p class="resource-deprecated">Deprecated: <p>message</p></p>`, which does not render correctly because paragraph tags cannot be nested. Also, in description lists, rendered markdown text was being wrapped in paragraph tags (e.g. `<dd><p>text</p></dd>`), causing it to render differently from text not wrapped in paragraph tags (e.g. `<dd>text</dd>`). This change addresses these issues. - First, `<div class="resource-deprecated">` is used rather than `<p>` to contain the deprecation information. - Second, the `markdownify` function will now trim unnecessary paragraph tags. Fixes https://github.com/pulumi/pulumi-hugo/issues/2832 Fixes https://github.com/pulumi/registry/issues/3008 --- ## Before <img width="713" alt="Screen Shot 2023-08-24 at 5 21 44 PM" src="https://github.com/pulumi/pulumi/assets/710598/1358cc74-dd8a-4bc0-bed8-603b1439b2aa"> ## After <img width="721" alt="Screen Shot 2023-08-24 at 5 21 58 PM" src="https://github.com/pulumi/pulumi/assets/710598/ad501e68-1bac-486c-a723-7db2b3442c8a"> ## Before <img width="719" alt="Screen Shot 2023-08-24 at 5 22 28 PM" src="https://github.com/pulumi/pulumi/assets/710598/6ca40b85-9008-429b-83c3-2f0d681752f3"> ## After <img width="714" alt="Screen Shot 2023-08-24 at 5 24 02 PM" src="https://github.com/pulumi/pulumi/assets/710598/eec1dacf-8c24-470e-b1e3-da843b4aeaee">
2023-08-26 17:36:28 +00:00
<div class="resource-deprecated">Deprecated: {{ markdownify .DeprecationMessage -}}</div>
{{- end }}
{{ htmlSafe .Comment }}
{{- if ne (len .ExamplesSection) 0 }}
{{ template "examples" .ExamplesSection }}
{{- end }}
<!-- Input properties -->
## Using {{ .Header.Title }} {#using}
{{- if .AnyLanguageHasOutputVersion }}
Two invocation forms are available. The direct form accepts plain
arguments and either blocks until the result value is available, or
returns a Promise-wrapped result. The output form accepts
Input-wrapped arguments and returns an Output-wrapped result.
{{- end }}
<div>
<pulumi-chooser type="language" options="typescript,python,go,csharp,java,yaml"></pulumi-chooser>
</div>
<!-- TS/JS -->
2022-04-29 22:04:15 +00:00
<div>
<pulumi-choosable type="language" values="javascript,typescript">
<div class="highlight"
><pre class="chroma"><code class="language-typescript" data-lang="typescript"
><span class="k">function </span>{{ .FunctionName.nodejs }}<span class="p">(</span>{{ htmlSafe .FunctionArgs.nodejs }}<span class="p">): Promise<{{ template "linkify_param" .FunctionResult.nodejs }}></span
{{- if .HasOutputVersion.nodejs }}
><span class="k">
function </span>{{ .FunctionName.nodejs }}Output<span class="p">(</span>{{ htmlSafe .FunctionArgsOutputVersion.nodejs }}<span class="p">): Output<{{ template "linkify_param" .FunctionResult.nodejs }}></span
{{- end }}
></code></pre></div>
2022-04-29 22:04:15 +00:00
</pulumi-choosable>
</div>
<!-- Python -->
2022-04-29 22:04:15 +00:00
<div>
<pulumi-choosable type="language" values="python">
<div class="highlight"><pre class="chroma"><code class="language-python" data-lang="python"
><span class="k">def </span>{{ .FunctionName.python }}<span class="p">(</span>{{ htmlSafe .FunctionArgs.python }}<span class="p">) -&gt;</span> <span>{{ .FunctionResult.python.Name }}</span
{{- if .HasOutputVersion.python }}
><span class="k">
def </span>{{ .FunctionName.python }}_output<span class="p">(</span>{{ htmlSafe .FunctionArgsOutputVersion.python }}<span class="p">) -&gt;</span> <span>Output[{{ .FunctionResult.python.Name }}]</span
{{- end }}
></code></pre></div>
2022-04-29 22:04:15 +00:00
</pulumi-choosable>
</div>
<!-- Go -->
2022-04-29 22:04:15 +00:00
<div>
<pulumi-choosable type="language" values="go">
<div class="highlight"><pre class="chroma"><code class="language-go" data-lang="go"
><span class="k">func </span>{{ .FunctionName.go }}<span class="p">(</span>{{ htmlSafe .FunctionArgs.go }}<span class="p">) (*{{ template "linkify_param" .FunctionResult.go }}, error)</span
{{- if .HasOutputVersion.go }}
><span class="k">
func </span>{{ .FunctionName.go }}Output<span class="p">(</span>{{ htmlSafe .FunctionArgsOutputVersion.go }}<span class="p">) {{ .FunctionResultOutputVersion.go.Name }}</span
{{- end }}
></code></pre></div>
{{ if ne .FunctionName.go .Header.Title }}
&gt; Note: This function is named `{{ .FunctionName.go }}` in the Go SDK.
{{ end }}
2022-04-29 22:04:15 +00:00
</pulumi-choosable>
</div>
<!-- C# -->
2022-04-29 22:04:15 +00:00
<div>
<pulumi-choosable type="language" values="csharp">
<div class="highlight"><pre class="chroma"><code class="language-csharp" data-lang="csharp"><span class="k">public static class </span><span class="nx">{{ .FunctionName.csharp }} </span><span class="p">
{</span><span class="k">
public static </span>Task<{{ template "linkify_param" .FunctionResult.csharp }}> <span class="p">InvokeAsync(</span>{{ htmlSafe .FunctionArgs.csharp }}<span class="p">)</span>{{- if .HasOutputVersion.csharp }}<span class="k">
public static </span>Output<{{ template "linkify_param" .FunctionResult.csharp }}> <span class="p">Invoke(</span>{{ htmlSafe .FunctionArgsOutputVersion.csharp }}<span class="p">)</span>{{- end }}<span class="p">
2020-03-31 11:07:04 +00:00
}</span></code></pre></div>
2022-04-29 22:04:15 +00:00
</pulumi-choosable>
</div>
2022-04-21 11:23:36 +00:00
<!-- Java -->
<div>
<pulumi-choosable type="language" values="java">
2022-04-21 11:23:36 +00:00
<div class="highlight"><pre class="chroma"><code class="language-java" data-lang="java"><span class="k">public static CompletableFuture<{{ template "linkify_param" .FunctionResult.java }}> </span>{{ .FunctionName.java }}<span class="p">(</span>{{ htmlSafe .FunctionArgs.java }}<span class="p">)</span>
<span class="c">// Output-based functions aren't available in Java yet</span>
</code></pre></div>
</pulumi-choosable>
</div>
2022-04-21 11:23:36 +00:00
<!-- YAML -->
<div>
<pulumi-choosable type="language" values="yaml">
2022-11-04 18:12:58 +00:00
<div class="highlight"><pre class="chroma"><code class="language-yaml" data-lang="yaml"><span class="k">fn::invoke:</span>
<span class="k">&nbsp;&nbsp;function:</span> {{ .FunctionName.yaml }}
<span class="k">&nbsp;&nbsp;arguments:</span>
<span class="c">&nbsp;&nbsp;&nbsp;&nbsp;# arguments dictionary</span></code></pre></div>
</pulumi-choosable>
</div>
2022-04-21 11:23:36 +00:00
{{ if ne (len .InputProperties) 0 }}
The following arguments are supported:
{{ template "properties" .InputProperties }}
{{ end }}
<!-- Output properties -->
## {{.Header.Title}} Result {#result}
The following output properties are available:
{{ template "properties" .OutputProperties }}
<!-- Supporting types -->
{{ if ne (len .NestedTypes) 0 }}
## Supporting Types
{{ range .NestedTypes }}
<h4 id="{{ .AnchorID }}">{{ htmlSafe .Name }}</h4>
{{ template "properties" .Properties }}
{{ end }}
{{ end }}
{{ template "package_details" .PackageDetails }}