WIP: snippet generator interface

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DirectedDocGen.java

@@ -5,6 +5,10 @@
 
 package software.amazon.smithy.docgen.core;
 
+import java.util.ArrayList;
+import java.util.List;
+import java.util.ServiceLoader;
+import software.amazon.smithy.build.PluginContext;
 import software.amazon.smithy.codegen.core.SymbolProvider;
 import software.amazon.smithy.codegen.core.directed.CreateContextDirective;
 import software.amazon.smithy.codegen.core.directed.CreateSymbolProviderDirective;
@@ -21,6 +25,8 @@
 import software.amazon.smithy.docgen.core.generators.OperationGenerator;
 import software.amazon.smithy.docgen.core.generators.ResourceGenerator;
 import software.amazon.smithy.docgen.core.generators.ServiceGenerator;
+import software.amazon.smithy.docgen.core.generators.SnippetGenerator;
+import software.amazon.smithy.docgen.core.generators.SnippetGenerator.SnippetComparator;
 import software.amazon.smithy.docgen.core.generators.StructuredShapeGenerator;
 import software.amazon.smithy.model.node.ExpectationNotMetException;
 import software.amazon.smithy.model.traits.InputTrait;
@@ -33,19 +39,39 @@
 @SmithyUnstableApi
 final class DirectedDocGen implements DirectedCodegen<DocGenerationContext, DocSettings, DocIntegration> {
 
+    private final PluginContext pluginContext;
+
+    DirectedDocGen(PluginContext pluginContext) {
+        this.pluginContext = pluginContext;
+    }
+
     @Override
     public SymbolProvider createSymbolProvider(CreateSymbolProviderDirective<DocSettings> directive) {
         return new DocSymbolProvider(directive.model(), directive.settings());
     }
 
     @Override
     public DocGenerationContext createContext(CreateContextDirective<DocSettings, DocIntegration> directive) {
+        var contextGenerator = new MockPluginContextGenerator(
+                pluginContext, directive.settings().snippetGeneratorSettings());
+        var classLoader = pluginContext.getPluginClassLoader().orElse(getClass().getClassLoader());
+
+        List<SnippetGenerator> snippetGenerators = new ArrayList<>();
+        for (SnippetGenerator generator : ServiceLoader.load(SnippetGenerator.class, classLoader)) {
+            var pluginContext = contextGenerator.getStubbedContext(directive.model(), generator.name());
+            if (generator.configure(pluginContext, directive.service())) {
+                snippetGenerators.add(generator);
+            }
+        }
+        snippetGenerators = snippetGenerators.stream().sorted(new SnippetComparator()).toList();
+
         return new DocGenerationContext(
-            directive.model(),
-            directive.settings(),
-            directive.symbolProvider(),
-            directive.fileManifest(),
-            directive.integrations()
+                directive.model(),
+                directive.settings(),
+                directive.symbolProvider(),
+                directive.fileManifest(),
+                directive.integrations(),
+                snippetGenerators
         );
     }
 

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocGenerationContext.java

@@ -13,6 +13,7 @@
 import software.amazon.smithy.codegen.core.SymbolProvider;
 import software.amazon.smithy.codegen.core.WriterDelegator;
 import software.amazon.smithy.docgen.core.DocSymbolProvider.FileExtensionDecorator;
+import software.amazon.smithy.docgen.core.generators.SnippetGenerator;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.utils.SmithyUnstableApi;
@@ -30,6 +31,7 @@ public final class DocGenerationContext implements CodegenContext<DocSettings, D
     private final WriterDelegator<DocWriter> writerDelegator;
     private final List<DocIntegration> docIntegrations;
     private final DocFormat docFormat;
+    private final List<SnippetGenerator> snippetGenerators;
 
     /**
      * Constructor.
@@ -39,13 +41,15 @@ public final class DocGenerationContext implements CodegenContext<DocSettings, D
      * @param symbolProvider The symbol provider to use to turn shapes into symbols.
      * @param fileManifest The file manifest to write to.
      * @param docIntegrations A list of integrations to apply during generation.
+     * @param snippetGenerators A list of snippet generators to add snippets to docs.
      */
     public DocGenerationContext(
             Model model,
             DocSettings docSettings,
             SymbolProvider symbolProvider,
             FileManifest fileManifest,
-            List<DocIntegration> docIntegrations
+            List<DocIntegration> docIntegrations,
+            List<SnippetGenerator> snippetGenerators
     ) {
         this.model = model;
         this.docSettings = docSettings;
@@ -74,6 +78,7 @@ public DocGenerationContext(
         this.docFormat = resolvedFormat;
         this.symbolProvider = symbolProvider;
         this.writerDelegator = new WriterDelegator<>(fileManifest, symbolProvider, resolvedFormat.writerFactory());
+        this.snippetGenerators = snippetGenerators;
     }
 
     @Override
@@ -112,4 +117,11 @@ public List<DocIntegration> integrations() {
     public DocFormat docFormat() {
         return this.docFormat;
     }
+
+    /**
+     * @return returns the generators used to add snippets to docs.
+     */
+    public List<SnippetGenerator> snippetGenerators() {
+        return snippetGenerators;
+    }
 }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSettings.java

@@ -6,6 +6,7 @@
 package software.amazon.smithy.docgen.core;
 
 import java.util.Objects;
+import software.amazon.smithy.model.node.Node;
 import software.amazon.smithy.model.node.ObjectNode;
 import software.amazon.smithy.model.shapes.ShapeId;
 import software.amazon.smithy.utils.SmithyUnstableApi;
@@ -16,9 +17,12 @@
  *
  * @param service The shape id of the service to generate documentation for.
  * @param format The format to generate documentation in. The default is markdown.
+ * @param snippetGeneratorSettings Settings to pass along to snippet generators. By
+ *        default, the settings for the plugin in the current projection will be used,
+ *        if available.
  */
 @SmithyUnstableApi
-public record DocSettings(ShapeId service, String format) {
+public record DocSettings(ShapeId service, String format, ObjectNode snippetGeneratorSettings) {
 
     /**
      * Settings for documentation generation. These can be set in the
@@ -30,6 +34,7 @@ public record DocSettings(ShapeId service, String format) {
     public DocSettings {
         Objects.requireNonNull(service);
         Objects.requireNonNull(format);
+        Objects.requireNonNull(snippetGeneratorSettings);
     }
 
     /**
@@ -41,7 +46,8 @@ public record DocSettings(ShapeId service, String format) {
     public static DocSettings fromNode(ObjectNode pluginSettings) {
         return new DocSettings(
             pluginSettings.expectStringMember("service").expectShapeId(),
-            pluginSettings.getStringMemberOrDefault("format", "sphinx-markdown")
+            pluginSettings.getStringMemberOrDefault("format", "sphinx-markdown"),
+            pluginSettings.getObjectMember("snippetGeneratorSettings").orElse(Node.objectNode())
         );
     }
 }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/MockPluginContextGenerator.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core;
+
+import java.util.Optional;
+import software.amazon.smithy.build.MockManifest;
+import software.amazon.smithy.build.PluginContext;
+import software.amazon.smithy.build.model.ProjectionConfig;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * Generates mock plugin contexts to pass along to snippet generators.
+ */
+@SmithyUnstableApi
+class MockPluginContextGenerator {
+    private final PluginContext baseContext;
+    private final ObjectNode pluginSettings;
+
+    /**
+     * Constructs a MockPluginContextGenerator.
+     *
+     * @param baseContext The context to base plugin context generation on.
+     * @param pluginSettings Settings specifically given to pass to plugins via the doc generator.
+     */
+    MockPluginContextGenerator(PluginContext baseContext, ObjectNode pluginSettings) {
+        if (baseContext.getProjection().isEmpty()) {
+            // PluginContext will NPE if there's no projection config so you have to do it manually
+            // until that gets fixed.
+            var builder = PluginContext.builder()
+                    .projection(baseContext.getProjectionName(), ProjectionConfig.builder().build())
+                    .model(baseContext.getModel())
+                    .originalModel(baseContext.getOriginalModel().orElse(baseContext.getModel()))
+                    .events(baseContext.getEvents())
+                    .settings(baseContext.getSettings())
+                    .fileManifest(baseContext.getFileManifest())
+                    .sources(baseContext.getSources());
+            baseContext.getPluginClassLoader().ifPresent(builder::pluginClassLoader);
+            baseContext.getOriginalModel().ifPresent(builder::originalModel);
+            baseContext.getArtifactName().ifPresent(builder::artifactName);
+            baseContext = builder.build();
+        }
+        this.baseContext = baseContext;
+        this.pluginSettings = pluginSettings;
+    }
+
+    /**
+     * Create a new plugin context with the given model and plugin name.
+     *
+     * @param model The version of the model to hand to the plugin.
+     * @param pluginName The name of the plugin. This is used to search for existing config.
+     * @return Returns a plugin context with the given model and config for the named plugin.
+     */
+    PluginContext getStubbedContext(Model model, String pluginName) {
+        ObjectNode settings = pluginSettings.getObjectMember(pluginName)
+                .or(() -> baseContext.getProjection()
+                        .map(ProjectionConfig::getPlugins)
+                        .flatMap(plugins -> Optional.ofNullable(plugins.get(pluginName))))
+                .orElse(Node.objectNode());
+
+        return baseContext.toBuilder()
+                .fileManifest(new MockManifest())
+                .artifactName(pluginName)
+                .model(model)
+                .settings(settings)
+                .build();
+    }
+}

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/SmithyDocPlugin.java

@@ -42,7 +42,7 @@ public void execute(PluginContext pluginContext) {
         CodegenDirector<DocWriter, DocIntegration, DocGenerationContext, DocSettings> runner
                 = new CodegenDirector<>();
 
-        runner.directedCodegen(new DirectedDocGen());
+        runner.directedCodegen(new DirectedDocGen(pluginContext));
         runner.integrationClass(DocIntegration.class);
         runner.fileManifest(pluginContext.getFileManifest());
         runner.model(getValidatedModel(pluginContext.getModel()).unwrap());

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/ExampleInputGenerator.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core.generators;
+
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.shapes.OperationShape;
+import software.amazon.smithy.model.shapes.Shape;
+import software.amazon.smithy.model.traits.ExamplesTrait.Example;
+
+public class ExampleInputGenerator implements SnippetGenerator {
+    @Override
+    public String name() {
+        return "input";
+    }
+
+    @Override
+    public boolean isWireProtocolGenerator() {
+        return true;
+    }
+
+    @Override
+    public String tabTitle() {
+        return "Input";
+    }
+
+    @Override
+    public String language() {
+        return "json";
+    }
+
+    @Override
+    public String generateShapeSnippet(Shape shape, Node value) {
+        return "";
+    }
+
+    @Override
+    public String generateExampleSnippet(OperationShape operation, Example example) {
+        return Node.prettyPrintJson(example.getInput());
+    }
+}

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/ExampleOutputGenerator.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core.generators;
+
+import software.amazon.smithy.model.node.Node;
+import software.amazon.smithy.model.shapes.OperationShape;
+import software.amazon.smithy.model.shapes.Shape;
+import software.amazon.smithy.model.traits.ExamplesTrait.Example;
+
+public class ExampleOutputGenerator implements SnippetGenerator {
+    @Override
+    public String name() {
+        return "output";
+    }
+
+    @Override
+    public String tabTitle() {
+        return "Output";
+    }
+
+    @Override
+    public String language() {
+        return "json";
+    }
+
+    @Override
+    public String generateShapeSnippet(Shape shape, Node value) {
+        return "";
+    }
+
+    @Override
+    public String generateExampleSnippet(OperationShape operation, Example example) {
+        return Node.prettyPrintJson(example.getOutput().orElse(Node.objectNode()));
+    }
+}

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/OperationGenerator.java

@@ -21,7 +21,6 @@
 import software.amazon.smithy.docgen.core.sections.ShapeSubheadingSection;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
 import software.amazon.smithy.docgen.core.writers.DocWriter.ListType;
-import software.amazon.smithy.model.node.Node;
 import software.amazon.smithy.model.shapes.OperationShape;
 import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.model.traits.ExamplesTrait;
@@ -168,17 +167,11 @@ private void writeExamples(
             example.getDocumentation().ifPresent(writer::writeCommonMark);
 
             writer.openTabGroup();
-            // TODO: create example writer interface allow integrations to register them
-
-            // This is just a dummy placehodler tab here to exercise tab creation before
-            // there's an interface for it.
-            writer.openCodeTab("Input", "json");
-            writer.write(Node.prettyPrintJson(example.getInput()));
-            writer.closeCodeTab();
-            writer.openCodeTab("Output", "json");
-            writer.write(Node.prettyPrintJson(example.getOutput().orElse(Node.objectNode())));
-            writer.closeCodeTab();
-
+            for (var snippetGenerator : context.snippetGenerators()) {
+                writer.openCodeTab(snippetGenerator.tabTitle(), snippetGenerator.language());
+                writer.write(snippetGenerator.generateExampleSnippet(operation, example));
+                writer.closeCodeTab();
+            }
             writer.closeTabGroup();
 
             writer.closeHeading();