Merge pull request #9 from smithy-lang/shape-generation

Generate docs for structures and members

Author: JordonPhillips

smithy-docgen-core/build.gradle

@@ -16,4 +16,5 @@ dependencies {
     implementation("software.amazon.smithy:smithy-model:$smithyVersion")
     implementation("software.amazon.smithy:smithy-utils:$smithyVersion")
     implementation("software.amazon.smithy:smithy-codegen-core:$smithyVersion")
+    implementation("software.amazon.smithy:smithy-linters:$smithyVersion")
 }

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

@@ -17,6 +17,7 @@
 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.docgen.core.generators.StructureGenerator;
 import software.amazon.smithy.utils.SmithyUnstableApi;
 
 /**
@@ -48,7 +49,7 @@ public void generateService(GenerateServiceDirective<DocGenerationContext, DocSe
 
     @Override
     public void generateStructure(GenerateStructureDirective<DocGenerationContext, DocSettings> directive) {
-        // no-op for now
+        new StructureGenerator().accept(directive);
     }
 
     @Override

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

@@ -9,6 +9,7 @@
 
 import java.util.Locale;
 import java.util.Objects;
+import java.util.Optional;
 import java.util.logging.Logger;
 import software.amazon.smithy.codegen.core.Symbol;
 import software.amazon.smithy.codegen.core.SymbolProvider;
@@ -17,9 +18,11 @@
 import software.amazon.smithy.model.shapes.ServiceShape;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.shapes.ShapeVisitor;
+import software.amazon.smithy.model.shapes.StructureShape;
 import software.amazon.smithy.model.traits.StringTrait;
 import software.amazon.smithy.model.traits.TitleTrait;
 import software.amazon.smithy.utils.SmithyUnstableApi;
+import software.amazon.smithy.utils.StringUtils;
 
 /**
  * Creates documentation Symbols for each shape in the model.
@@ -31,11 +34,11 @@
  *     <li>{@code name}: The name of the symbol will be used as the title for its
  *     definition section. For services, this defaults to the value of the
  *     {@code title} trait. For other shapes, it defaults to the shape name including
- *     any renames from the attached service. For members, the member name is appended
- *     to the parent with a separating {@code -}.
+ *     any renames from the attached service.
  *     <li>{@code definitionFile}: The file in which the documentation for this shape
  *     should be written. By default these are all written to a single flat directory.
- *     If this is empty, the shape does not have its own definition section.
+ *     If this is empty, the shape does not have its own definition section and cannot
+ *     be linked to.
  *     <li>{@link #SHAPE_PROPERTY}: A named Shape property containing the shape that
  *     the symbol represents. Decorators provided by
  *     {@link DocIntegration#decorateSymbolProvider} MUST set or preserve this
@@ -128,23 +131,39 @@ public Symbol serviceShape(ServiceShape shape) {
             .build();
     }
 
+    @Override
+    public Symbol structureShape(StructureShape shape) {
+        return getSymbolBuilder(shape)
+                .definitionFile(getDefinitionFile(serviceShape, shape))
+                .build();
+    }
+
+    @Override
+    public Symbol memberShape(MemberShape shape) {
+        var builder = getSymbolBuilder(shape)
+                .definitionFile(getDefinitionFile(serviceShape, model.expectShape(shape.getId().withoutMember())));
+
+        Optional<String> containerLinkId = model.expectShape(shape.getContainer())
+                .accept(this)
+                .getProperty(LINK_ID_PROPERTY, String.class);
+        if (containerLinkId.isPresent()) {
+            var linkId = containerLinkId.get() + "-" + getLinkId(getShapeName(serviceShape, shape));
+            builder.putProperty(LINK_ID_PROPERTY, linkId);
+        }
+        return builder.build();
+    }
+
     private Symbol.Builder getSymbolBuilder(Shape shape) {
         var name = getShapeName(serviceShape, shape);
         return Symbol.builder()
-            .name(name)
-            .putProperty(SHAPE_PROPERTY, shape)
-            .definitionFile(getDefinitionFile(serviceShape, shape))
-            .putProperty(LINK_ID_PROPERTY, getLinkId(name))
-            .putProperty(ENABLE_DEFAULT_FILE_EXTENSION, true);
+                .name(name)
+                .putProperty(SHAPE_PROPERTY, shape)
+                .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+", "")
-        );
+        return getDefinitionFile(getShapeName(serviceShape, shape).replaceAll("\\s+", ""));
     }
 
     private String getDefinitionFile(String filename) {
@@ -157,11 +176,11 @@ private String getShapeName(ServiceShape serviceShape, Shape shape) {
                 .map(StringTrait::getValue)
                 .orElse(shape.getId().getName());
         }
-        var name = shape.getId().getName(serviceShape);
         if (shape.isMemberShape()) {
-            name += "-" + toMemberName(shape.asMemberShape().get());
+            return toMemberName(shape.asMemberShape().get());
+        } else {
+            return shape.getId().getName(serviceShape);
         }
-        return name;
     }
 
     private String getLinkId(String shapeName) {
@@ -172,7 +191,7 @@ private String getLinkId(String shapeName) {
     // have impact.
     @Override
     protected Symbol getDefault(Shape shape) {
-        return null;
+        return getSymbolBuilder(shape).build();
     }
 
     /**
@@ -209,7 +228,7 @@ public Symbol toSymbol(Shape shape) {
         }
 
         private String addExtension(String path) {
-            if (!path.endsWith(extension)) {
+            if (!StringUtils.isBlank(path) && !path.endsWith(extension)) {
                 path += extension;
             }
             return path;

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

@@ -12,11 +12,15 @@
 import java.io.InputStreamReader;
 import java.nio.charset.Charset;
 import java.nio.file.Path;
+import java.nio.file.Paths;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Optional;
 import java.util.logging.Logger;
 import software.amazon.smithy.codegen.core.CodegenException;
+import software.amazon.smithy.codegen.core.Symbol;
 import software.amazon.smithy.utils.SmithyUnstableApi;
+import software.amazon.smithy.utils.StringUtils;
 
 /**
  * Provides various utility methods.
@@ -83,4 +87,29 @@ public static String runCommand(String command, Path directory) {
     public static String normalizeNewlines(String input) {
         return input.replaceAll("\r?\n", System.lineSeparator());
     }
+
+    /**
+     * Gets a relative link pointing to a given symbol.
+     *
+     * <p>If the given symbol has no definition file or no
+     * {@link DocSymbolProvider#LINK_ID_PROPERTY}, the response will be empty.
+     *
+     * @param symbol The symbol to link to.
+     * @param relativeTo A path that the symbol should be relative to. This must be the
+     *                   path to the file containing the link.
+     * @return Optionally returns a relative link to the given symbol.
+     */
+    public static Optional<String> getSymbolLink(Symbol symbol, Path relativeTo) {
+        Optional<String> linkId = symbol.getProperty(DocSymbolProvider.LINK_ID_PROPERTY, String.class);
+        var relativeToParent = relativeTo.getParent();
+        if (StringUtils.isBlank(symbol.getDefinitionFile())
+                || linkId.isEmpty()
+                || StringUtils.isBlank(linkId.get())
+                || relativeToParent == null) {
+            return Optional.empty();
+        }
+        return Optional.of(format(
+                "./%s#%s", relativeToParent.relativize(Paths.get(symbol.getDefinitionFile())), linkId.get()
+        ));
+    }
 }

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

@@ -6,11 +6,21 @@
 package software.amazon.smithy.docgen.core;
 
 
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
 import java.util.logging.Logger;
 import software.amazon.smithy.build.PluginContext;
 import software.amazon.smithy.build.SmithyBuildPlugin;
 import software.amazon.smithy.codegen.core.directed.CodegenDirector;
+import software.amazon.smithy.docgen.core.validation.DocValidationEventDecorator;
 import software.amazon.smithy.docgen.core.writers.DocWriter;
+import software.amazon.smithy.linters.InputOutputStructureReuseValidator;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.validation.ValidatedResult;
+import software.amazon.smithy.model.validation.ValidationEvent;
+import software.amazon.smithy.model.validation.ValidationEventDecorator;
+import software.amazon.smithy.model.validation.suppressions.ModelBasedEventDecorator;
 import software.amazon.smithy.utils.SmithyInternalApi;
 
 /**
@@ -29,19 +39,44 @@ public String getName() {
     @Override
     public void execute(PluginContext pluginContext) {
         LOGGER.fine("Beginning documentation generation.");
-        DocSettings docSettings = DocSettings.from(pluginContext.getSettings());
+        DocSettings settings = DocSettings.from(pluginContext.getSettings());
 
         CodegenDirector<DocWriter, DocIntegration, DocGenerationContext, DocSettings> runner
                 = new CodegenDirector<>();
 
         runner.directedCodegen(new DirectedDocGen());
         runner.integrationClass(DocIntegration.class);
         runner.fileManifest(pluginContext.getFileManifest());
-        runner.model(pluginContext.getModel());
-        runner.settings(docSettings);
-        runner.service(docSettings.service());
+        runner.model(getValidatedModel(pluginContext.getModel()).unwrap());
+        runner.settings(settings);
+        runner.service(settings.service());
         runner.performDefaultCodegenTransforms();
         runner.run();
         LOGGER.fine("Finished documentation generation.");
     }
+
+    private ValidatedResult<Model> getValidatedModel(Model model) {
+        // This decorator will add context for why these are particularly important for docs.
+        ValidationEventDecorator eventDecorator = new DocValidationEventDecorator();
+
+        // This will discover and apply suppressions from the model.
+        Optional<ValidationEventDecorator> modelDecorator = new ModelBasedEventDecorator()
+                .createDecorator(model).getResult();
+        if (modelDecorator.isPresent()) {
+            eventDecorator = ValidationEventDecorator.compose(List.of(modelDecorator.get(), eventDecorator));
+        }
+
+        var events = new ArrayList<ValidationEvent>();
+        for (var event : validate(model)) {
+            if (eventDecorator.canDecorate(event)) {
+                event = eventDecorator.decorate(event);
+            }
+            events.add(event);
+        }
+        return new ValidatedResult<>(model, events);
+    }
+
+    private List<ValidationEvent> validate(Model model) {
+        return new InputOutputStructureReuseValidator().validate(model);
+    }
 }