Support linking and write type links

JordonPhillips · JordonPhillips · commit 5864974a1c09 · 2023-10-30T17:11:28.000+01:00
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSymbolProvider.java b/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.
@@ -34,7 +37,8 @@
  *     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
@@ -127,34 +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);
-        var containerLinkId = model.expectShape(shape.getContainer())
+        var builder = getSymbolBuilder(shape)
+                .definitionFile(getDefinitionFile(serviceShape, model.expectShape(shape.getId().withoutMember())));
+
+        Optional<String> containerLinkId = model.expectShape(shape.getContainer())
                 .accept(this)
-                .expectProperty(LINK_ID_PROPERTY, String.class);
-        var linkId = containerLinkId + "-" + getLinkId(getShapeName(serviceShape, shape));
-        builder.putProperty(LINK_ID_PROPERTY, linkId);
+                .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) {
@@ -219,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;
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocgenUtils.java b/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()
+        ));
+    }
 }
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/MemberGenerator.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/MemberGenerator.java
@@ -262,7 +262,7 @@ public Void unionShape(UnionShape shape) {
 
         private void writeShapeName(Shape shape) {
             var symbol = context.symbolProvider().toSymbol(shape);
-            writer.writeInline(symbol.getName());
+            writer.writeInline("$R", symbol);
         }
     }
 }
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/StructureGenerator.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/generators/StructureGenerator.java
@@ -9,6 +9,7 @@
 import software.amazon.smithy.codegen.core.directed.GenerateStructureDirective;
 import software.amazon.smithy.docgen.core.DocGenerationContext;
 import software.amazon.smithy.docgen.core.DocSettings;
+import software.amazon.smithy.docgen.core.DocSymbolProvider;
 import software.amazon.smithy.docgen.core.generators.MemberGenerator.MemberListingType;
 import software.amazon.smithy.docgen.core.sections.ShapeDetailsSection;
 import software.amazon.smithy.docgen.core.sections.ShapeSection;
@@ -63,6 +64,8 @@ public void accept(GenerateStructureDirective<DocGenerationContext, DocSettings>
         var symbol = directive.symbolProvider().toSymbol(shape);
         directive.context().writerDelegator().useShapeWriter(shape, writer -> {
             writer.pushState(new ShapeSection(directive.context(), shape));
+
+            symbol.getProperty(DocSymbolProvider.LINK_ID_PROPERTY, String.class).ifPresent(writer::writeAnchor);
             writer.openHeading(symbol.getName());
 
             writer.writeShapeDocs(shape, directive.model());
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocWriter.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocWriter.java
@@ -22,17 +22,49 @@
 public abstract class DocWriter extends SymbolWriter<DocWriter, DocImportContainer> {
     private static final int MAX_HEADING_DEPTH = 6;
 
+    /**
+     * The full path to the file being written to by the writer.
+     */
+    protected final String filename;
+
     private int headingDepth = 0;
 
     /**
      * Constructor.
      *
      * @param importContainer The container to store any imports in.
+     * @param filename The name of the file being written.
      */
-    public DocWriter(DocImportContainer importContainer) {
+    public DocWriter(DocImportContainer importContainer, String filename) {
         super(importContainer);
+        this.filename = filename;
+        putFormatter('R', (s, i) -> referenceFormatter(s));
     }
 
+    /**
+     * Formats the given reference object as a link if possible.
+     *
+     * <p>This given value can be expected to be one of the following types:
+     *
+     * <ul>
+     *     <li>{@code Symbol}: The symbol's name is the link text and a combination of
+     *     the definition file and {@link software.amazon.smithy.docgen.core.DocSymbolProvider#LINK_ID_PROPERTY}
+     *     forms the actual link. If either the link id or definition file are not set,
+     *     the formatter must return the symbol's name.
+     *     <li>{@code SymbolReference}: The reference's alias is the link text and a
+     *     combination of the referenced symbol's definition file and
+     *     {@link software.amazon.smithy.docgen.core.DocSymbolProvider#LINK_ID_PROPERTY}
+     *     forms the actual link. If either the link id or definition file are not set,
+     *     the formatter should return the reference's alias.
+     *     <li>{@code Pair<String, String>}: The key is the link text and the value is
+     *     the link. Both key and value MUST be present.
+     * </ul>
+     *
+     * @param value The value to format.
+     * @return returns a string formatted to reference the given value.
+     */
+    abstract String referenceFormatter(Object value);
+
     /**
      * Writes out the content of the shape's
      * <a href="https://smithy.io/2.0/spec/documentation-traits.html#smithy-api-documentation-trait">
@@ -72,6 +104,20 @@ public DocWriter openHeading(String content) {
         return openHeading(content, headingDepth);
     }
 
+    /**
+     * Writes a heading with the given content and linkId.
+     *
+     * <p>{@link #closeHeading} will be called to enable cleaning up any resources or
+     * context this method creates.
+     *
+     * @param content A string to use as the heading content.
+     * @param linkId The identifier used to link to the heading.
+     * @return returns the writer.
+     */
+    public DocWriter openHeading(String content, String linkId) {
+        return writeAnchor(linkId).openHeading(content);
+    }
+
     /**
      * Writes a heading of a given level with the given content.
      *
@@ -147,4 +193,18 @@ public DocWriter closeHeading() {
      * @return returns the writer.
      */
     public abstract DocWriter closeMemberEntry();
+
+    /**
+     * Writes a linkable element to the documentation with the given identifier.
+     *
+     * <p>The resulting HTML should be able to link to this anchor with {@code #linkId}.
+     *
+     * <p>For example, a direct HTML writer might create a {@code span} tag with
+     * the given string as the tag's {@code id}, or modify the next emitted tag
+     * to have the given id.
+     *
+     * @param linkId The anchor's link identifier.
+     * @return returns the writer.
+     */
+    public abstract DocWriter writeAnchor(String linkId);
 }
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/MarkdownWriter.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/MarkdownWriter.java
@@ -5,13 +5,19 @@
 
 package software.amazon.smithy.docgen.core.writers;
 
+import static software.amazon.smithy.docgen.core.DocgenUtils.getSymbolLink;
+
+import java.nio.file.Paths;
 import java.util.Optional;
 import java.util.function.Consumer;
+import software.amazon.smithy.codegen.core.CodegenException;
 import software.amazon.smithy.codegen.core.Symbol;
+import software.amazon.smithy.codegen.core.SymbolReference;
 import software.amazon.smithy.codegen.core.SymbolWriter;
 import software.amazon.smithy.model.Model;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.traits.DocumentationTrait;
+import software.amazon.smithy.utils.Pair;
 import software.amazon.smithy.utils.SmithyUnstableApi;
 import software.amazon.smithy.utils.StringUtils;
 
@@ -22,22 +28,74 @@
 public class MarkdownWriter extends DocWriter {
 
     /**
-     * Constructor.
+     * Constructs a MarkdownWriter.
+     *
+     * @param importContainer this file's import container.
+     * @param filename The full path to the file being written to.
+     */
+    public MarkdownWriter(DocImportContainer importContainer, String filename) {
+        super(importContainer, filename);
+    }
+
+
+    /**
+     * Constructs a MarkdownWriter.
+     *
+     * @param filename The full path to the file being written to.
      */
-    public MarkdownWriter() {
-        super(new DocImportContainer());
+    public MarkdownWriter(String filename) {
+        this(new DocImportContainer(), filename);
     }
 
     /**
      * Factory to construct {@code MarkdownWriter}s.
      */
     public static final class Factory implements SymbolWriter.Factory<DocWriter> {
         @Override
-        public DocWriter apply(String s, String s1) {
-            return new MarkdownWriter();
+        public DocWriter apply(String filename, String namespace) {
+            return new MarkdownWriter(filename);
         }
     }
 
+    @Override
+    String referenceFormatter(Object value) {
+        var reference = getReferencePair(value);
+        if (reference.getRight().isPresent()) {
+            return String.format("[%s](%s)", reference.getLeft(), reference.getRight().get());
+        } else {
+            return reference.getLeft();
+        }
+    }
+
+    private Pair<String, Optional<String>> getReferencePair(Object value) {
+        String text;
+        Optional<String> ref;
+        var relativeTo = Paths.get(filename);
+        if (value instanceof Symbol symbolValue) {
+            text = symbolValue.getName();
+            ref = getSymbolLink(symbolValue, relativeTo);
+        } else if (value instanceof SymbolReference referenceValue) {
+            text = referenceValue.getAlias();
+            ref = getSymbolLink(referenceValue.getSymbol(), relativeTo);
+        } else if (value instanceof Pair pairValue) {
+            if (pairValue.getLeft() instanceof String left && pairValue.getRight() instanceof String right) {
+                text = left;
+                ref = Optional.of(right);
+            } else {
+                throw new CodegenException(
+                        "Invalid type provided to $R. Expected both key and vale of the Pair to be Strings, but "
+                        + "found " + value.getClass()
+                );
+            }
+        } else {
+            throw new CodegenException(
+                    "Invalid type provided to $R. Expected a Symbol, SymbolReference, or Pair<String, String>, but "
+                    + "found " + value.getClass()
+            );
+        }
+        return Pair.of(text, ref);
+    }
+
     @Override
     public DocWriter writeShapeDocs(Shape shape, Model model) {
         Optional<DocumentationTrait> docTrait;
@@ -84,6 +142,12 @@ public DocWriter closeMemberEntry() {
         return this;
     }
 
+    @Override
+    public DocWriter writeAnchor(String linkId) {
+        // Anchors have no meaning in base markdown
+        return this;
+    }
+
     @Override
     public String toString() {
         // Ensure there's exactly one trailing newline
diff --git a/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/SphinxMarkdownWriter.java b/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/SphinxMarkdownWriter.java
diff --git a/smithy-docgen-test/model/main.smithy b/smithy-docgen-test/model/main.smithy

Original file line number	Diff line number	Diff line change
`@@ -262,7 +262,7 @@ public Void unionShape(UnionShape shape) {`
`262`	`262`
`263`	`263`	`private void writeShapeName(Shape shape) {`
`264`	`264`	`var symbol = context.symbolProvider().toSymbol(shape);`
`265`		`- writer.writeInline(symbol.getName());`
	`265`	`+ writer.writeInline("$R", symbol);`
`266`	`266`	`}`
`267`	`267`	`}`
`268`	`268`	`}`