Refactor SOS templates to use nested templates and add curated exampl…

…e templates (awsdocs#4186) * Refactor SOS templates to use nested templates. Add curated examples as a new example type that can be published (but don't add any yet). * Add placeholder sources.yaml so the linter finds something to lint. Co-authored-by: Steven Meyer <[email protected]>
cubiccompass · Jan 6, 2023 · 4db4420 · 4db4420
1 parent 0241fe8
commit 4db4420
Show file tree

Hide file tree

Showing 23 changed files with 462 additions and 517 deletions.
diff --git a/.doc_gen/metadata/curated/sources.yaml b/.doc_gen/metadata/curated/sources.yaml
@@ -0,0 +1,4 @@
+placeholder-examples:
+  name: Placeholder curated examples
+  description: Placeholder source description until we add actual curated examples.
+  url: https://github.com/aws/not-a-real-repo
diff --git a/.doc_gen/templates/zonbook/example_curated_template.xml b/.doc_gen/templates/zonbook/example_curated_template.xml
@@ -0,0 +1,30 @@
+{{- template "prologue"}}
+{{- $include_docs := "file://AWSShared/code-samples/docs/"}}
+{{- if isSnapshot}}
+    {{- $include_docs := ""}}
+{{- end}}
+<block>
+    {{- if .BlockContent}}
+    <xi:include href="{{$include_docs}}{{.BlockContent}}"></xi:include>
+    {{- else}}
+    <para>{{.Description}}</para>
+    {{- if .DescriptionList}}
+    <itemizedlist>
+        {{- range $desc := .DescriptionList}}
+        <listitem><para>{{$desc}}</para></listitem>
+        {{- end}}
+    </itemizedlist>
+    {{- end}}
+    {{- end}}
+    <para>
+        For complete source code and instructions on how to set up and run, see
+        <ulink url="{{.UrlHref}}">{{.UrlText}}</ulink> in
+        <emphasis>{{.SourceName}}</emphasis>.
+    </para>
+    <itemizedlist>
+        <title>Services used in this example</title>
+        {{- range $svc_ent := $.Services}}
+        <listitem><para>{{$svc_ent.Short}}</para></listitem>
+        {{- end}}
+    </itemizedlist>
+</block>
diff --git a/.doc_gen/templates/zonbook/example_description_template.xml b/.doc_gen/templates/zonbook/example_description_template.xml
@@ -1,36 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file://zonbook/docbookx.dtd"[
-{{- if isSnapshot}}
-    <!ENTITY % phrases-code-examples SYSTEM "phrases-code-examples.ent">
-{{- else}}
-    <!ENTITY % phrases-code-examples SYSTEM "file://AWSShared/code-samples/docs/phrases-code-examples.ent">
-{{- end}}
-    %phrases-code-examples;
-    <!ENTITY % phrases-shared SYSTEM "file://AWSShared/common/phrases-shared.ent">
-    %phrases-shared;
-]>
-<!-- zexi 0.2.0 -->
-{{- $synopsis_prefix := "The following code examples show how to"}}
-{{- $synopsis_sep := " "}}
-{{- $synopsis := "use this service with some of the &AWS; SDKs that are available."}}
-{{- if eq .ExampleCount 1}}
-    {{- $synopsis_prefix = "The following code example shows how to"}}
-{{- end}}
-{{- if .Synopsis}}
-    {{- $synopsis = .Synopsis}}
-{{- else}}
-    {{- if .SynopsisList}}
-        {{- $synopsis_sep = ":"}}
-        {{- $synopsis = ""}}
-    {{- end}}
-{{- end}}
+{{- template "prologue"}}
 <block>
-    <para>{{$synopsis_prefix}}{{$synopsis_sep}}{{$synopsis}}</para>
-    {{- if .SynopsisList}}
-    <itemizedlist>
-        {{- range $synitem := .SynopsisList}}
-        <listitem><para>{{$synitem}}</para></listitem>
-        {{- end}}
-    </itemizedlist>
-    {{- end}}
+{{- template "service_synopsis" .}}
 </block>
diff --git a/.doc_gen/templates/zonbook/example_language_template.xml b/.doc_gen/templates/zonbook/example_language_template.xml
@@ -1,17 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file://zonbook/docbookx.dtd"[
-    <!ENTITY % xinclude SYSTEM "file://AWSShared/common/xinclude.mod">
-    %xinclude;
-{{- if isSnapshot}}
-    <!ENTITY % phrases-code-examples SYSTEM "phrases-code-examples.ent">
-{{- else}}
-    <!ENTITY % phrases-code-examples SYSTEM "file://AWSShared/code-samples/docs/phrases-code-examples.ent">
-{{- end}}
-    %phrases-code-examples;
-    <!ENTITY % phrases-shared SYSTEM "file://AWSShared/common/phrases-shared.ent">
-    %phrases-shared;
-]>
-<!-- zexi 0.4.0 -->
+{{- template "prologue"}}
 {{- $include_base := "file://AWSShared/"}}
 {{- $include_docs := "file://AWSShared/code-samples/docs/"}}
 {{- if isSnapshot}}
@@ -86,4 +73,4 @@
         </listitem>
     </varlistentry>
     {{- end}}
-</variablelist>
+</variablelist>
diff --git a/.doc_gen/templates/zonbook/example_tablist_template.xml b/.doc_gen/templates/zonbook/example_tablist_template.xml
@@ -1,8 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file://zonbook/docbookx.dtd"[
-    <!ENTITY % xinclude SYSTEM "file://AWSShared/common/xinclude.mod">
-    %xinclude;
-]>
+{{- template "prologue"}}
 {{- $include_docs := "file://AWSShared/code-samples/docs/"}}
 {{- if isSnapshot}}
     {{- $include_docs = ""}}

diff --git a/.doc_gen/templates/zonbook/library_by_sdk_chapter.xml b/.doc_gen/templates/zonbook/library_by_sdk_chapter.xml
@@ -1,17 +1,4 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "file://zonbook/docbookx.dtd"[
-    <!ENTITY % xinclude SYSTEM "file://AWSShared/common/xinclude.mod">
-    %xinclude;
-{{- if isSnapshot}}
-    <!ENTITY % phrases-code-examples SYSTEM "phrases-code-examples.ent">
-{{- else}}
-    <!ENTITY % phrases-code-examples SYSTEM "file://AWSShared/code-samples/docs/phrases-code-examples.ent">
-{{- end}}
-    %phrases-code-examples;
-    <!ENTITY % phrases-shared SYSTEM "file://AWSShared/common/phrases-shared.ent">
-    %phrases-shared;
-]>
-<!-- zexi 0.5.0 -->
+{{- template "prologue"}}
 {{- $omitted_sdks := makeSlice "java_1"}}
 {{- $chapter_id := "code_example_library_by_sdk"}}
 {{- $include_docs := "file://AWSShared/code-samples/docs/"}}
@@ -47,141 +34,8 @@
         </info>
         <para>The code examples in this topic show you how to use the {{$sdk_examples.SdkEntity.Long}} with &AWS;.</para>
         <para role="topiclist-abbrev">Examples</para>
-        {{- if $sdk_examples.ApiExamples}}
-        <section id="{{$sdk_ver}}_code_examples_categorized" role="topic">
-            <info>
-                <title id="{{$sdk_ver}}_code_examples_categorized.title">Single-service actions and scenarios using {{$sdk_examples.SdkEntity.Short}}</title>
-                <titleabbrev id="{{$sdk_ver}}_code_examples_categorized.titleabbrev">Single-service actions and scenarios</titleabbrev>
-                <abstract>
-                    <para>The following code examples show how to implement common scenarios and perform individual service actions by using
-                        {{$sdk_examples.SdkEntity.Short}} with &AWS-services;.</para>
-                </abstract>
-            </info>
-            <para>The following code examples show how to perform actions and implement common scenarios by using
-                the {{$sdk_examples.SdkEntity.Long}} with &AWS-services;.</para>
-            <para><emphasis>Actions</emphasis> are code excerpts that show you how to call individual service functions.</para>
-            <para><emphasis>Scenarios</emphasis> are code examples that show you how to accomplish a specific task by
-                calling multiple functions within the same service.</para>
-            <para role="topiclist-abbrev">Services</para>
-            {{- end}}
-            {{- range $service, $svc_examples := $sdk_examples.ApiExamples}}
-            <section id="{{$sdk_ver}}_{{$svc_examples.ServiceSlug}}_code_examples" role="topic">
-                <info>
-                    <title id="{{$sdk_ver}}_{{$svc_examples.ServiceSlug}}_code_examples.title">{{$svc_examples.ServiceEntity.Short}} examples using {{$sdk_examples.SdkEntity.Short}}</title>
-                    <titleabbrev id="{{$sdk_ver}}_{{$svc_examples.ServiceSlug}}_code_examples.titleabbrev">{{$svc_examples.ServiceEntity.Short}}</titleabbrev>
-                    <abstract>
-                        <para>Code examples that show how to use {{$sdk_examples.SdkEntity.Long}} with {{$svc_examples.ServiceEntity.Short}}.</para>
-
-                    </abstract>
-                    <keywordset>
-                        <keyword>code example</keyword>
-                        <keyword>&AWS; SDK</keyword>
-                        <keyword>{{$svc_examples.ServiceEntity.Long}}</keyword>
-                        <keyword>{{$sdk_examples.SdkEntity.Long}}</keyword>
-                    </keywordset>
-                </info>
-                <para>The following code examples show you how to perform actions and implement common scenarios by using
-                    the {{$sdk_examples.SdkEntity.Long}} with {{$svc_examples.ServiceEntity.Long}}.</para>
-                <para><emphasis>Actions</emphasis> are code excerpts that show you how to call individual service functions.</para>
-                <para><emphasis>Scenarios</emphasis> are code examples that show you how to accomplish a specific task
-                    by calling multiple functions within the same service.</para>
-                {{- $hello := index $svc_examples.CategorizedExampleSets "Hello"}}
-                {{- if $hello.Examples}}
-                <para><emphasis role="bold">Get started</emphasis></para>
-                <block>
-                    <collapsible expand-section="_collapse_all_">
-                        {{- range $hello.Examples}}
-                        <section id="example_{{.ExampleId}}_section">
-                            <info>
-                                <title id="example_{{.ExampleId}}_section.title">{{.Title}}</title>
-                                <titleabbrev id="example_{{.ExampleId}}_section.titleabbrev">{{.TitleAbbrev}}</titleabbrev>
-                                <abstract>
-                                    <para>{{.Title}}</para>
-                                </abstract>
-                            </info>
-                            <xi:include href="{{$include_docs}}{{.ExampleId}}_desc.xml"></xi:include>
-                            <xi:include href="{{$include_docs}}{{.ExampleId}}_{{$sdk_examples.Language}}.xml"></xi:include>
-                        </section>
-                        {{- end}}
-                    </collapsible>
-                </block>
-                {{- end}}
-                <para role="topiclist-abbrev"/>
-                {{- range $category := $svc_examples.CategoryNamesSorted}}
-                {{- if ne $category "Hello"}}
-                {{- with $cat_examples := index $svc_examples.CategorizedExampleSets $category}}
-                <section>
-                    <info>
-                        <title>{{$cat_examples.CategoryName}}</title>
-                        <titleabbrev>{{$cat_examples.CategoryName}}</titleabbrev>
-                    </info>
-                    <collapsible expand-section="_collapse_all_">
-                        {{- range $cat_examples.Examples}}
-                        <section id="{{.ExampleId}}_{{$sdk_ver}}_topic">
-                            <info>
-                                <title id="{{.ExampleId}}_{{$sdk_ver}}_topic.title">{{.TitleAbbrev}}</title>
-                                <titleabbrev id="{{.ExampleId}}_{{$sdk_ver}}_topic.titleabbrev">{{.TitleAbbrev}}</titleabbrev>
-                            </info>
-                            {{- if or .Synopsis .SynopsisList}}
-                                {{- $synopsis_prefix := "The following code example shows how to"}}
-                                {{- $synopsis_sep := " "}}
-                                {{- if not .Synopsis}}
-                                    {{- $synopsis_sep = ":"}}
-                                {{- end}}
-                            <para>{{print $synopsis_prefix $synopsis_sep .Synopsis}}</para>
-                                {{- if .SynopsisList}}
-                            <itemizedlist>
-                                {{- range $synitem := .SynopsisList}}
-                                <listitem><para>{{$synitem}}</para></listitem>
-                                {{- end}}
-                            </itemizedlist>
-                                {{- end}}
-                            {{- end}}
-                            {{- if .GuideTopic.Url}}
-                            <para>For more information, see <ulink {{.GuideTopic.DocType}} url="{{.GuideTopic.Url}}">{{.GuideTopic.Text}}</ulink>.</para>
-                            {{- end}}
-                            <xi:include href="{{$include_docs}}{{.ExampleId}}_{{$sdk_examples.Language}}.xml"></xi:include>
-                        </section>
-                        {{- end}}
-                    </collapsible>
-                </section>
-                {{- end}}
-                {{- end}}
-                {{- end}}
-            </section>
-            {{- end}}
-            {{- if $sdk_examples.ApiExamples}}
-        </section>
-        {{- end}}
-        {{- if $sdk_examples.CrossServiceExamples}}
-        <section id="{{$sdk_ver}}_code_examples_cross_service" role="topic">
-            <info>
-                <title id="{{$sdk_ver}}_code_examples_cross_service.title">Cross-service examples using {{$sdk_examples.SdkEntity.Short}}</title>
-                <titleabbrev id="{{$sdk_ver}}_code_examples_cross_service.titleabbrev">Cross-service examples</titleabbrev>
-                <abstract>
-                    <para>The following sample applications use the {{$sdk_examples.SdkEntity.Long}}
-                        to work across multiple &AWS-services;.</para>
-                </abstract>
-            </info>
-            <para>The following sample applications use the {{$sdk_examples.SdkEntity.Long}}
-                to work across multiple &AWS-services;.</para>
-            <para role="topiclist-abbrev">Examples</para>
-            {{- end}}
-            {{- range $sdk_examples.CrossServiceExamples}}
-            <section id="{{.ExampleId}}_{{$sdk_ver}}_topic" role="topic">
-                <info>
-                    <title id="{{.ExampleId}}_{{$sdk_ver}}_topic.title">{{.Title}}</title>
-                    <titleabbrev id="{{.ExampleId}}_{{$sdk_ver}}_topic.titleabbrev">{{.TitleAbbrev}}</titleabbrev>
-                </info>
-                <xi:include href="{{$include_docs}}{{.ExampleId}}_{{$sdk_examples.Language}}.xml"></xi:include>
-                {{- if .GuideTopic.Url}}
-                <para>For more information, see <ulink {{.GuideTopic.DocType}} url="{{.GuideTopic.Url}}">{{.GuideTopic.Text}}</ulink>.</para>
-                {{- end}}
-            </section>
-            {{- end}}
-        {{- if $sdk_examples.CrossServiceExamples}}
-        </section>
-        {{- end}}
+        {{- template "sdk_api_examples" makeSlice $sdk_examples $sdk_ver}}
+        {{- template "sdk_cross_examples" makeSlice $sdk_examples $sdk_ver}}
     </section>
     {{- end}}
     {{- end}}