Improve heading nesting error

Author: JordonPhillips

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

@@ -54,7 +54,7 @@ private static String getDefinitionFile(ServiceShape serviceShape, Shape shape)
     }
 
     public static String getDefinitionFile(String filename) {
-        return "sources/" + filename;
+        return "content/" + filename;
     }
 
     private static String getShapeName(ServiceShape serviceShape, Shape shape) {

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

@@ -20,10 +20,10 @@ public void accept(GenerateServiceDirective<DocGenerationContext, DocSettings> d
         ServiceShape serviceShape = directive.service();
 
         directive.context().writerDelegator().useShapeWriter(serviceShape, writer -> {
-            writer.openHeader(serviceShape.expectTrait(TitleTrait.class).getValue());
+            writer.openHeading(serviceShape.expectTrait(TitleTrait.class).getValue());
             writer.writeShapeDocs(serviceShape);
 
-            writer.closeHeader();
+            writer.closeHeading();
         });
     }
 

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocWriter.java

@@ -15,7 +15,7 @@ public DocWriter(DocImportContainer importContainer) {
 
     public abstract DocWriter writeShapeDocs(Shape shape);
 
-    public abstract DocWriter openHeader(String content);
+    public abstract DocWriter openHeading(String content);
 
-    public abstract DocWriter closeHeader();
+    public abstract DocWriter closeHeading();
 }

smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/MarkdownWriter.java

@@ -5,13 +5,15 @@
 
 package software.amazon.smithy.docgen.core.writers;
 
+import software.amazon.smithy.codegen.core.CodegenException;
 import software.amazon.smithy.codegen.core.SymbolWriter;
 import software.amazon.smithy.model.shapes.Shape;
 import software.amazon.smithy.model.traits.DocumentationTrait;
 import software.amazon.smithy.utils.StringUtils;
 
-public final class MarkdownWriter
-    extends DocWriter {
+public final class MarkdownWriter extends DocWriter {
+    private static int MAX_HEADING_DEPTH = 6;
+
     private int headerLevel = 0;
 
     public MarkdownWriter() {
@@ -40,10 +42,13 @@ private DocWriter writeWithNewline(Object content, Object... args) {
     }
 
     @Override
-    public DocWriter openHeader(String content) {
+    public DocWriter openHeading(String content) {
         headerLevel++;
-        if (headerLevel > 5) {
-            throw new RuntimeException("Tried opening a header nested too deeply.");
+        if (headerLevel > MAX_HEADING_DEPTH) {
+            throw new CodegenException(String.format(
+                "Tried opening a heading nested more deeply than the max depth of %d.",
+                MAX_HEADING_DEPTH
+            ));
         }
 
         writeWithNewline(StringUtils.repeat("#", headerLevel) + " " + content);
@@ -52,9 +57,9 @@ public DocWriter openHeader(String content) {
     }
 
     @Override
-    public DocWriter closeHeader() {
+    public DocWriter closeHeading() {
         if (headerLevel <= 0) {
-            throw new RuntimeException("Closed a header that was never opened.");
+            throw new CodegenException("Closed a header that was never opened.");
         }
         write("");