Enable format selection

This adds the capability to select a doc format and add make new
formats available via integrations.

Author: JordonPhillips

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/BuiltInDocFormatsIntegration.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 java.util.List;
+import software.amazon.smithy.docgen.core.writers.MarkdownWriter;
+import software.amazon.smithy.utils.SmithyInternalApi;
+
+/**
+ * Applies the built-in {@link DocFormat}s.
+ */
+@SmithyInternalApi
+public class BuiltInDocFormatsIntegration implements DocIntegration {
+    @Override
+    public List<DocFormat> docFormats(DocSettings settings) {
+        return List.of(
+            new DocFormat("markdown", ".md", new MarkdownWriter.Factory())
+        );
+    }
+}

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

@@ -0,0 +1,27 @@
+/*
+ * 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.SymbolWriter;
+import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * A record containing information about a doc format.
+ *
+ * <p>Use {@link DocIntegration#docFormats} to make new formats available.
+ *
+ * @param name The name of the format. This will be the string that will be set as the
+ *             value of {@code format} in {@link DocSettings}.
+ * @param extension The file extension to use by default for documentation files. This
+ *                  will be set on the {@code Symbol}s automatically by
+ *                  {@link software.amazon.smithy.docgen.core.DocSymbolProvider.FileExtensionDecorator}.
+ * @param writerFactory A factory method for creating writers that write in this
+ *                      format.
+ */
+@SmithyUnstableApi
+public record DocFormat(String name, String extension, SymbolWriter.Factory<DocWriter> writerFactory) {
+}

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

@@ -5,13 +5,15 @@
 
 package software.amazon.smithy.docgen.core;
 
+import java.util.LinkedHashSet;
 import java.util.List;
 import software.amazon.smithy.build.FileManifest;
 import software.amazon.smithy.codegen.core.CodegenContext;
+import software.amazon.smithy.codegen.core.CodegenException;
 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.writers.DocWriter;
-import software.amazon.smithy.docgen.core.writers.MarkdownWriter;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.utils.SmithyUnstableApi;
 
@@ -27,6 +29,7 @@ public final class DocGenerationContext implements CodegenContext<DocSettings, D
     private final FileManifest fileManifest;
     private final WriterDelegator<DocWriter> writerDelegator;
     private final List<DocIntegration> docIntegrations;
+    private final DocFormat docFormat;
 
     /**
      * Constructor.
@@ -46,11 +49,31 @@ public DocGenerationContext(
     ) {
         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;
+
+        DocFormat resolvedFormat = null;
+        var availableFormats = new LinkedHashSet<String>();
+        for (var integration : docIntegrations) {
+            for (var format : integration.docFormats(docSettings)) {
+                if (format.name().equals(docSettings.format())) {
+                    resolvedFormat = format;
+                    symbolProvider = new FileExtensionDecorator(symbolProvider, resolvedFormat.extension());
+                    break;
+                }
+                availableFormats.add(format.name());
+            }
+        }
+        if (resolvedFormat == null) {
+            throw new CodegenException(String.format(
+                "Unknown doc format `%s`. You may be missing a dependency. Currently available formats: [%s]",
+                docSettings.format(), String.join(", ", availableFormats)
+            ));
+        }
+
+        this.docFormat = resolvedFormat;
+        this.symbolProvider = symbolProvider;
+        this.writerDelegator = new WriterDelegator<>(fileManifest, symbolProvider, resolvedFormat.writerFactory());
     }
 
     @Override
@@ -82,4 +105,11 @@ public WriterDelegator<DocWriter> writerDelegator() {
     public List<DocIntegration> integrations() {
         return docIntegrations;
     }
+
+    /**
+     * @return Returns the selected format that documentation should be generated in.
+     */
+    public DocFormat docFormat() {
+        return this.docFormat;
+    }
 }

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

@@ -5,6 +5,7 @@
 
 package software.amazon.smithy.docgen.core;
 
+import java.util.List;
 import software.amazon.smithy.codegen.core.SmithyIntegration;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
 import software.amazon.smithy.utils.SmithyUnstableApi;
@@ -20,4 +21,18 @@
  */
 @SmithyUnstableApi
 public interface DocIntegration extends SmithyIntegration<DocSettings, DocWriter, DocGenerationContext> {
+
+    /**
+     * Adds {@link DocFormat}s to the list of supported formats.
+     *
+     * <p>When resolving the format implementation, the first format found with a
+     * matching name will be used. Use {@link #priority} to adjust which integration
+     * is seen first.
+     *
+     * @param settings The documentation generation settings.
+     * @return A list of formats to add.
+     */
+    default List<DocFormat> docFormats(DocSettings settings) {
+        return List.of();
+    }
 }

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

@@ -15,18 +15,21 @@
  * {@code smithy-build.json} configuration for this plugin.
  *
  * @param service The shape id of the service to generate documentation for.
+ * @param format The format to generate documentation in. The default is markdown.
  */
 @SmithyUnstableApi
-public record DocSettings(ShapeId service) {
+public record DocSettings(ShapeId service, String format) {
 
     /**
      * 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.
+     * @param format The format to generate documentation in. The default is markdown.
      */
     public DocSettings {
         Objects.requireNonNull(service);
+        Objects.requireNonNull(format);
     }
 
     /**
@@ -36,6 +39,9 @@ public record DocSettings(ShapeId service) {
      * @return loaded settings based on the given node.
      */
     public static DocSettings from(ObjectNode pluginSettings) {
-        return new DocSettings(pluginSettings.expectStringMember("service").expectShapeId());
+        return new DocSettings(
+            pluginSettings.expectStringMember("service").expectShapeId(),
+            pluginSettings.getStringMemberOrDefault("format", "markdown")
+        );
     }
 }

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

@@ -8,10 +8,12 @@
 import static java.lang.String.format;
 
 import java.util.Locale;
+import java.util.Objects;
 import java.util.logging.Logger;
 import software.amazon.smithy.codegen.core.Symbol;
 import software.amazon.smithy.codegen.core.SymbolProvider;
 import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.MemberShape;
 import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.shapes.ShapeVisitor;
@@ -44,6 +46,10 @@
  *     to the shape's definition might look like {@code https://example.com/shapes#foo}
  *     for example. If this or {@code definitionFile} is empty, it is not possible to
  *     link to the shape.
+ *     <li>{@link #ENABLE_DEFAULT_FILE_EXTENSION}: A named boolean property indicating
+ *     whether the symbol's definition file should have the default file extension
+ *     applied. If not present or set to {@code false}, the file extension will not be
+ *     applied.
  * </ul>
  *
  * <p>Decorators provided by {@link DocIntegration#decorateSymbolProvider} MUST set
@@ -80,6 +86,16 @@ public final class DocSymbolProvider extends ShapeVisitor.Default<Symbol> implem
      */
     public static final String LINK_ID_PROPERTY = "linkId";
 
+    /**
+     * A named boolean property indicating whether the symbol's definition file should
+     * have the default file extension applied. If not present or set to {@code false},
+     * the file extension will not be applied.
+     *
+     * <p>Use {@code symbol.getProperty(LINK_ID_PROPERTY, Boolean.class)} to access this
+     * property.
+     */
+    public static final String ENABLE_DEFAULT_FILE_EXTENSION = "enableDefaultFileExtension";
+
     private static final Logger LOGGER = Logger.getLogger(DocSymbolProvider.class.getName());
 
     private final Model model;
@@ -118,15 +134,16 @@ private Symbol.Builder getSymbolBuilder(Shape shape) {
             .name(name)
             .putProperty(SHAPE_PROPERTY, shape)
             .definitionFile(getDefinitionFile(serviceShape, shape))
-            .putProperty(LINK_ID_PROPERTY, getLinkId(name));
+            .putProperty(LINK_ID_PROPERTY, getLinkId(name))
+            .putProperty(ENABLE_DEFAULT_FILE_EXTENSION, true);
     }
 
     private String getDefinitionFile(ServiceShape serviceShape, Shape shape) {
         if (shape.isMemberShape()) {
             return getDefinitionFile(serviceShape, model.expectShape(shape.getId().withoutMember()));
         }
         return getDefinitionFile(
-            getShapeName(serviceShape, shape).replaceAll("\\s+", "") + ".md"
+            getShapeName(serviceShape, shape).replaceAll("\\s+", "")
         );
     }
 
@@ -157,4 +174,50 @@ private String getLinkId(String shapeName) {
     protected Symbol getDefault(Shape shape) {
         return null;
     }
+
+    /**
+     * Adds file extensions to symbol definition files. Used with {@link DocFormat}
+     * by default.
+     *
+     * <p>Symbols can set {@link #ENABLE_DEFAULT_FILE_EXTENSION} to {@code false} to
+     * disable this on a per-symbol basis.
+     */
+    public static final class FileExtensionDecorator implements SymbolProvider {
+        private final SymbolProvider wrapped;
+        private final String extension;
+
+        /**
+         * Constructor.
+         * @param wrapped The symbol provider to wrap.
+         * @param extension The file extension to add. This must include any necessary periods.
+         */
+        public FileExtensionDecorator(SymbolProvider wrapped, String extension) {
+            this.wrapped = Objects.requireNonNull(wrapped);
+            this.extension = Objects.requireNonNull(extension);
+        }
+
+        @Override
+        public Symbol toSymbol(Shape shape) {
+            var symbol = wrapped.toSymbol(shape);
+            if (!symbol.getProperty(ENABLE_DEFAULT_FILE_EXTENSION, Boolean.class).orElse(false)) {
+                return symbol;
+            }
+            return symbol.toBuilder()
+                .definitionFile(addExtension(symbol.getDefinitionFile()))
+                .declarationFile(addExtension(symbol.getDeclarationFile()))
+                .build();
+        }
+
+        private String addExtension(String path) {
+            if (!path.endsWith(extension)) {
+                path += extension;
+            }
+            return path;
+        }
+
+        @Override
+        public String toMemberName(MemberShape shape) {
+            return wrapped.toMemberName(shape);
+        }
+    }
 }

smithy-docgen-core/src/main/resources/META-INF/services/software.amazon.smithy.docgen.core.DocIntegration

@@ -0,0 +1 @@
+software.amazon.smithy.docgen.core.BuiltInDocFormatsIntegration