Merge pull request #3 from smithy-lang/base-generation

Add base generation capability

Author: JordonPhillips

config/checkstyle/checkstyle.xml

@@ -22,7 +22,7 @@
     <!-- Files must contain a copyright header, with or without a year. -->
     <module name="RegexpHeader">
         <property name="header"
-                  value="/\*\n \* Copyright( 20(23)|) Amazon\.com, Inc\. or its affiliates\. All Rights Reserved\.\n"/>
+                  value="/\*\n \* Copyright Amazon\.com, Inc\. or its affiliates\. All Rights Reserved\.\n"/>
         <property name="fileExtensions" value="java"/>
     </module>
 

gradle.properties

@@ -1,2 +1,2 @@
-smithyVersion=1.33.0
-smithyGradleVersion=0.7.0
+smithyVersion=[1.39.1,2.0)
+smithyGradleVersion=0.8.0

smithy-docgen-core/build.gradle

@@ -22,5 +22,8 @@ ext {
 }
 
 dependencies {
-    api("software.amazon.smithy:smithy-build:$smithyVersion")
+    implementation("software.amazon.smithy:smithy-build:$smithyVersion")
+    implementation("software.amazon.smithy:smithy-model:$smithyVersion")
+    implementation("software.amazon.smithy:smithy-utils:$smithyVersion")
+    implementation("software.amazon.smithy:smithy-codegen-core:$smithyVersion")
 }

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

@@ -0,0 +1,78 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core;
+
+import software.amazon.smithy.codegen.core.SymbolProvider;
+import software.amazon.smithy.codegen.core.directed.CreateContextDirective;
+import software.amazon.smithy.codegen.core.directed.CreateSymbolProviderDirective;
+import software.amazon.smithy.codegen.core.directed.DirectedCodegen;
+import software.amazon.smithy.codegen.core.directed.GenerateEnumDirective;
+import software.amazon.smithy.codegen.core.directed.GenerateErrorDirective;
+import software.amazon.smithy.codegen.core.directed.GenerateIntEnumDirective;
+import software.amazon.smithy.codegen.core.directed.GenerateResourceDirective;
+import software.amazon.smithy.codegen.core.directed.GenerateServiceDirective;
+import software.amazon.smithy.codegen.core.directed.GenerateStructureDirective;
+import software.amazon.smithy.codegen.core.directed.GenerateUnionDirective;
+import software.amazon.smithy.docgen.core.generators.ServiceGenerator;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * The main entry points for documentation generation.
+ */
+@SmithyUnstableApi
+final class DirectedDocGen implements DirectedCodegen<DocGenerationContext, DocSettings, DocIntegration> {
+
+    @Override
+    public SymbolProvider createSymbolProvider(CreateSymbolProviderDirective<DocSettings> directive) {
+        return new DocSymbolProvider(directive.model(), directive.settings());
+    }
+
+    @Override
+    public DocGenerationContext createContext(CreateContextDirective<DocSettings, DocIntegration> directive) {
+        return new DocGenerationContext(
+            directive.model(),
+            directive.settings(),
+            directive.symbolProvider(),
+            directive.fileManifest(),
+            directive.integrations()
+        );
+    }
+
+    @Override
+    public void generateService(GenerateServiceDirective<DocGenerationContext, DocSettings> directive) {
+        new ServiceGenerator().accept(directive);
+    }
+
+    @Override
+    public void generateStructure(GenerateStructureDirective<DocGenerationContext, DocSettings> directive) {
+        // no-op for now
+    }
+
+    @Override
+    public void generateError(GenerateErrorDirective<DocGenerationContext, DocSettings> directive) {
+        // no-op for now
+    }
+
+    @Override
+    public void generateUnion(GenerateUnionDirective<DocGenerationContext, DocSettings> directive) {
+        // no-op for now
+    }
+
+    @Override
+    public void generateEnumShape(GenerateEnumDirective<DocGenerationContext, DocSettings> directive) {
+        // no-op for now
+    }
+
+    @Override
+    public void generateIntEnumShape(GenerateIntEnumDirective<DocGenerationContext, DocSettings> directive) {
+        // no-op for now
+    }
+
+    @Override
+    public void generateResource(GenerateResourceDirective<DocGenerationContext, DocSettings> directive) {
+        // no-op for now
+    }
+}

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

@@ -0,0 +1,85 @@
+/*
+ * 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.List;
+import software.amazon.smithy.build.FileManifest;
+import software.amazon.smithy.codegen.core.CodegenContext;
+import software.amazon.smithy.codegen.core.SymbolProvider;
+import software.amazon.smithy.codegen.core.WriterDelegator;
+import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.docgen.core.writers.MarkdownWriter;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * Contextual information that is made available during most parts of documentation
+ * generation.
+ */
+@SmithyUnstableApi
+public final class DocGenerationContext implements CodegenContext<DocSettings, DocWriter, DocIntegration> {
+    private final Model model;
+    private final DocSettings docSettings;
+    private final SymbolProvider symbolProvider;
+    private final FileManifest fileManifest;
+    private final WriterDelegator<DocWriter> writerDelegator;
+    private final List<DocIntegration> docIntegrations;
+
+    /**
+     * Constructor.
+     *
+     * @param model The source model to generate for.
+     * @param docSettings Settings to customize generation.
+     * @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.
+     */
+    public DocGenerationContext(
+            Model model,
+            DocSettings docSettings,
+            SymbolProvider symbolProvider,
+            FileManifest fileManifest,
+            List<DocIntegration> docIntegrations
+    ) {
+        this.model = model;
+        this.docSettings = docSettings;
+        this.symbolProvider = symbolProvider;
+        this.fileManifest = fileManifest;
+        // TODO: pull the factory from the integrations
+        this.writerDelegator = new WriterDelegator<>(fileManifest, symbolProvider, new MarkdownWriter.Factory());
+        this.docIntegrations = docIntegrations;
+    }
+
+    @Override
+    public Model model() {
+        return model;
+    }
+
+    @Override
+    public DocSettings settings() {
+        return docSettings;
+    }
+
+    @Override
+    public SymbolProvider symbolProvider() {
+        return symbolProvider;
+    }
+
+    @Override
+    public FileManifest fileManifest() {
+        return fileManifest;
+    }
+
+    @Override
+    public WriterDelegator<DocWriter> writerDelegator() {
+        return writerDelegator;
+    }
+
+    @Override
+    public List<DocIntegration> integrations() {
+        return docIntegrations;
+    }
+}

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

@@ -0,0 +1,23 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package software.amazon.smithy.docgen.core;
+
+import software.amazon.smithy.codegen.core.SmithyIntegration;
+import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * Allows integrating additional functionality into the documentation generator.
+ *
+ * <p>{@code DocIntegration}s are loaded as a Java SPI. To make your integration
+ * discoverable, add a file to {@code META-INF/services} named
+ * {@code software.amazon.smithy.docgen.core.DocIntegration} where each line is
+ * the fully-qualified class name of your integrations. Several tools, such as
+ * {@code AutoService}, can do this for you.
+ */
+@SmithyUnstableApi
+public interface DocIntegration extends SmithyIntegration<DocSettings, DocWriter, DocGenerationContext> {
+}

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

@@ -0,0 +1,35 @@
+/*
+ * 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.Objects;
+import software.amazon.smithy.model.node.ObjectNode;
+import software.amazon.smithy.model.shapes.ShapeId;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * Settings for documentation generation. These can be set in the
+ * {@code smithy-build.json} configuration for this plugin.
+ *
+ * @param service The shape id of the service to generate documentation for.
+ */
+@SmithyUnstableApi
+public record DocSettings(ShapeId service) {
+
+    public DocSettings {
+        Objects.requireNonNull(service);
+    }
+
+    /**
+     * Load the settings from an {@code ObjectNode}.
+     *
+     * @param pluginSettings the {@code ObjectNode} to load settings from.
+     * @return loaded settings based on the given node.
+     */
+    public static DocSettings from(ObjectNode pluginSettings) {
+        return new DocSettings(pluginSettings.expectStringMember("service").expectShapeId());
+    }
+}