build(aio): improve the API Pipe pages (#22702)

This change adds:

* an impure badge for Pipes that are marked as  `pure: false`
* a pipe specific overview that shows the syntax for using a pipe in a template.
* an "input value" section describing the type of the value that the pipe expects.
* a "pipe params" section describing any additional params that a pipe expects.

PR Close #22702

aio/tools/transforms/templates/api/base.template.html

@@ -25,6 +25,7 @@
     {% if doc.deprecated !== undefined %}<label class="api-status-label deprecated">deprecated</label>{% endif %}
     {% if doc.experimental !== undefined %}<label class="api-status-label experimental">experimental</label>{% endif %}
     {% if doc.stable !== undefined %}<label class="api-status-label stable">stable</label>{% endif %}
+    {% if doc.pipeOptions.pure === 'false' %}<label class="api-status-label impure-pipe">impure</label>{% endif %}
   </header>
   <aio-toc class="embedded"></aio-toc>
 

aio/tools/transforms/templates/api/includes/pipe-overview.html

@@ -0,0 +1,21 @@
+{% import "lib/memberHelpers.html" as memberHelpers -%}
+{% import "lib/paramList.html" as params -%}
+
+<section class="{$ doc.docType $}-overview">
+  <code-example hideCopy="true" class="no-box api-heading">{{ {$ doc.valueParam.name $}_expression | <span class="kwd nocode">{$ doc.pipeName $}</span>
+    {%- for param in doc.pipeParams %}
+      {%- if param.isOptional or param.defaultValue !== undefined %} [{% endif %} : {$ param.name $}
+    {%- endfor %}
+    {%- for param in doc.pipeParams %}
+      {%- if param.isOptional or param.defaultValue !== undefined %} ]{% endif %}
+    {%- endfor %} }}</code-example>
+
+  {% if doc.valueParam.type %}
+  <h2>Input Value</h2>
+  {$ params.renderParameters([doc.valueParam], 'pipe-parameters', 'pipe-parameter', true) $}
+  {% endif %}
+  {% if doc.pipeParams.length %}
+  <h2>Parameters</h2>
+  {$ params.renderParameters(doc.pipeParams, 'pipe-parameters', 'pipe-parameter', true) $}
+  {% endif %}
+</section>

aio/tools/transforms/templates/api/lib/paramList.html

@@ -11,19 +11,20 @@
   {%- if returnType %}: {$ returnType | escape $}{% endif -%}
 {%- endmacro -%}
 
-{%- macro renderParameters(parameters, containerClass, parameterClass) -%}
+{%- macro renderParameters(parameters, containerClass, parameterClass, showType) -%}
 {%- if parameters.length -%}
 <table class="is-full-width list-table parameters-table {$ containerClass $}">
   <tbody>
   {% for parameter in parameters %}
     <tr class="{$ parameterClass $}">
       <td class="param-name"><a id="{$ parameter.anchor $}"></a>{$ parameter.name $}</td>
+      {% if showType %}<td class="param-type"><code>{$ parameter.type $}</code></td>{% endif %}
       <td class="param-description">
       {% marked %}
         {% if parameter.isOptional or parameter.defaultValue !== undefined %}Optional. Default is `{$ parameter.defaultValue === undefined and 'undefined' or parameter.defaultValue $}`.{% endif %}
 
         {% if parameter.description | trim %}{$ parameter.description $}
-        {% elseif parameter.type %}<code>{$ parameter.type $}</code>
+        {% elseif not showType and parameter.type %}<p>Type: <code>{$ parameter.type $}</code>.</p>
         {% endif %}
       {% endmarked %}
       </td>

aio/tools/transforms/templates/api/pipe.template.html

@@ -1,5 +1,8 @@
 {% extends 'export-base.template.html' -%}
 
+{% block overview %}
+{% include "includes/pipe-overview.html" %}
+{% endblock %}
 {% block details %}
 {% include "includes/description.html" %}
 {% endblock %}