Added Docgen files to the main smithy repo.

build.gradle.kts

@@ -46,12 +46,15 @@ val stagingDirectory = rootProject.layout.buildDirectory.dir("staging")
 
 subprojects {
     apply(plugin = "java-library")
-
     java {
-        sourceCompatibility = JavaVersion.VERSION_1_8
-        targetCompatibility = JavaVersion.VERSION_1_8
+        if (project.name == "smithy-docgen-core" || project.name == "smithy-docgen-test") {
+            sourceCompatibility = JavaVersion.VERSION_17
+            targetCompatibility = JavaVersion.VERSION_17
+        } else {
+            sourceCompatibility = JavaVersion.VERSION_1_8
+            targetCompatibility = JavaVersion.VERSION_1_8
+        }
     }
-
     repositories {
         mavenLocal()
         mavenCentral()

settings.gradle.kts

@@ -42,4 +42,6 @@ include(":smithy-aws-endpoints")
 include(":smithy-aws-smoke-test-model")
 include(":smithy-protocol-traits")
 include(":smithy-protocol-tests")
-include(":smithy-trait-codegen")
+include(":smithy-trait-codegen")
+include(":smithy-docgen-core")
+include(":smithy-docgen-test")

smithy-docgen-core/README.md

@@ -0,0 +1,197 @@
+## Smithy DocGen
+
+Smithy build plugin to generate API documentation from models authored in
+[Smithy](https://smithy.io) IDL.
+
+NOTE: this project is currently in a pre-release state. Interfaces and output
+formatting may change before full release.
+
+### Usage
+
+First, create a gradle-based Smithy model project. This can be done easily with
+the Smithy CLI: `smithy init -o /tmp/smithy-docgen -t quickstart-gradle`.
+
+Note: the generator currently cannot be run with non-gradle-based projects.
+
+Next, publish the generator to Maven local by running
+`./gradlew :smithy-docgen-core:publishToMavenLocal`.
+
+In `build.gradle.kts`, add
+`implementation("software.amazon.smithy:smithy-docgen-core:$smithyVersion")` under
+`implementation`.
+
+Next, add the `docgen` plugin to the
+[plugin configuration](https://smithy.io/2.0/guides/smithy-build-json.html) in
+`smithy-build.json`:
+
+```json
+"plugins": {
+    "docgen": {
+        "service": "example.weather#Weather"
+    }
+}
+```
+
+Finally, build the model with Gradle: `./gradlew build`
+
+Build logs will provide the destination folder for the generated docs.
+
+### Current State
+
+A documentation site can be generated in one of two formats with wide support
+for built-in traits. Minor changes to layout may occur, but the final product
+will be similar to the current output.
+
+The one critical, missing component is full example support. This will drive both
+wire-level examples and client examples.
+
+#### Trait Support
+
+Currently, most prelude (`smithy.api`) traits are supported, or deliberately
+excluded where not relevant to customer documentation. Trait information is
+easily added using Smithy's
+[interceptor](https://github.com/smithy-lang/smithy/blob/main/smithy-utils/src/main/java/software/amazon/smithy/utils/CodeInterceptor.java)
+system. Most trait information is added using interceptors, the implementations
+of which can be found in the
+[interceptors](https://github.com/smithy-lang/smithy-docgen/tree/main/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/interceptors)
+package.
+
+Auth traits are automatically supported as part of the service's auth list,
+where the trait's docs are used by default. More context can be added using
+the same interceptors that are run on normal shapes.
+
+##### Traits Missing Support
+
+The following prelude traits and trait categories are currently unsupported. All
+traits outside of the prelude are unsupported, with the exception of auth traits
+which have default support.
+
+* Protocol Traits - These should get a similar treatment to auth traits, where a
+  dedicated section is created for them and documentation is added without
+  needing to add explicit support. Each protocol also needs to be able to register
+  an example generator.
+* [Event Streaming](https://smithy.io/2.0/spec/streaming.html#event-streams)
+* [examples](https://smithy.io/2.0/spec/documentation-traits.html#smithy-api-examples-trait) -
+  The sections and wrapping for these are created, and currently there's a
+  stub that simply places the values of example inputs and outputs inside the
+  example blocks. An interface needs to be created for code generators to
+  actually integrate into this. Updates to directed codegen will likely be
+  needed to make this feasible. Protocols will need to implement this also.
+
+### Configuration
+
+This generator supports the following top-level configuration options:
+
+* `service` - The shape ID of the service to generate documentation for.
+* `format` - The format that the documentation should be generated in.
+* `references` - A map of resource shape ID to URL for resources referenced by
+  the [references trait](https://smithy.io/2.0/spec/resource-traits.html#references-trait)
+  that aren't included in service.
+
+```json
+{
+    "version": "1.0",
+    "projections": {
+        "plain-markdown": {
+            "plugins": {
+                "docgen": {
+                    "service": "com.example#MyService",
+                    "format": "markdown",
+                    "references": {
+                        "com.example#ExternalReference": "https://example.com/"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+#### Supported Formats
+
+The output format can be selected with the `format` configuration option. The
+example below demonstrtates selecting a plain markdown output format:
+
+```json
+{
+    "version": "1.0",
+    "projections": {
+        "plain-markdown": {
+            "plugins": {
+                "docgen": {
+                    "service": "com.example#MyService",
+                    "format": "markdown"
+                }
+            }
+        }
+    }
+}
+```
+
+By default, two formats are currently supported: `markdown` and
+`sphinx-markdown`. The `markdown` format renders docs as plain
+[CommonMark](https://commonmark.org), while `sphinx-commonmark` creates a
+[Sphinx](https://www.sphinx-doc.org/) markdown project that gets rendered to
+HTTP. `sphinx-markdown` is used by default.
+
+The generator is designed to allow for different output formats by supplying a
+new
+[DocWriter](https://github.com/smithy-lang/smithy-docgen/blob/main/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/DocWriter.java)
+via a
+[DocIntegration](https://github.com/smithy-lang/smithy-docgen/blob/main/smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocIntegration.java).
+
+##### sphinx-markdown
+
+The `sphinx-markdown` format uses Sphinx's markdown support provided by
+[MySt](https://myst-parser.readthedocs.io/en/latest/), which builds on top of
+CommonMark. By default, it will render the generated markdown into HTML as long
+as Python 3 is found on the path.
+
+* `format` (default: `html`) - The
+  [sphinx output format](https://www.sphinx-doc.org/en/master/usage/builders/index.html).
+* `theme` (default: [`furo`](https://github.com/pradyunsg/furo)) - The theme to
+  use for sphinx. If this is changed, the new theme will likely need to be added
+  to the `extraDependencies` list.
+* `extraDependencies` (default: `[]`) - A list of additional dependencies to be
+  added to the `requirements.txt` file, which is installed before building the
+  documentation.
+* `extraExtensions` (default: `[]`) - A list of additional sphinx extentions to
+  add to the sphinx extensions list in `conf.py`. Any additional extensions will
+  likely need to be added to the `extraDependencies` list.
+* `autoBuild` (default: `true`) - Whether to automatically render the
+  documentation to HTML. You may wish to disable autobuild if you want to add
+  additional documentation to the project before building, such as hand-written
+  guides.
+
+The following example `smithy-build.json` demonstrates configuring the
+`sphinx-markdown` format.
+
+```json
+{
+    "version": "1.0",
+    "projections": {
+        "sphinx-markdown": {
+            "plugins": {
+                "docgen": {
+                    "service": "com.example#DocumentedService",
+                    "format": "sphinx-markdown",
+                    "integrations": {
+                      "sphinx": {
+                        "format": "dirhtml",
+                        "autoBuild": false
+                      }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Security
+
+See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+
+## License
+
+This project is licensed under the Apache-2.0 License.

smithy-docgen-core/build.gradle.kts

@@ -0,0 +1,25 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+description = "This module contains support for generating API documentation " +
+        "based on Smithy models."
+
+
+extra["displayName"] = "Smithy :: DocGen :: Core"
+extra["moduleName"] = "software.amazon.smithy.docgen.core"
+
+dependencies {
+    api(project(":smithy-model"))
+    api(project(":smithy-build"))
+    api(project(":smithy-utils"))
+    api(project(":smithy-codegen-core"))
+    api(project(":smithy-linters"))
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(17))
+    }
+}

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

@@ -0,0 +1,98 @@
+/*
+ * 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.GenerateOperationDirective;
+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.MemberGenerator.MemberListingType;
+import software.amazon.smithy.docgen.core.generators.OperationGenerator;
+import software.amazon.smithy.docgen.core.generators.ResourceGenerator;
+import software.amazon.smithy.docgen.core.generators.ServiceGenerator;
+import software.amazon.smithy.docgen.core.generators.StructuredShapeGenerator;
+import software.amazon.smithy.model.node.ExpectationNotMetException;
+import software.amazon.smithy.model.traits.InputTrait;
+import software.amazon.smithy.model.traits.OutputTrait;
+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) {
+        // Input and output structures are documented alongside the relevant operations.
+        if (directive.shape().hasTrait(InputTrait.class) || directive.shape().hasTrait(OutputTrait.class)) {
+            return;
+        }
+        new StructuredShapeGenerator(directive.context()).accept(directive.shape(), MemberListingType.MEMBERS);
+    }
+
+    @Override
+    public void generateOperation(GenerateOperationDirective<DocGenerationContext, DocSettings> directive) {
+        new OperationGenerator().accept(directive);
+    }
+
+    @Override
+    public void generateError(GenerateErrorDirective<DocGenerationContext, DocSettings> directive) {
+        new StructuredShapeGenerator(directive.context()).accept(directive.shape(), MemberListingType.MEMBERS);
+    }
+
+    @Override
+    public void generateUnion(GenerateUnionDirective<DocGenerationContext, DocSettings> directive) {
+        new StructuredShapeGenerator(directive.context()).accept(directive.shape(), MemberListingType.OPTIONS);
+    }
+
+    @Override
+    public void generateEnumShape(GenerateEnumDirective<DocGenerationContext, DocSettings> directive) {
+        new StructuredShapeGenerator(directive.context()).accept(directive.shape(), MemberListingType.OPTIONS);
+    }
+
+    @Override
+    public void generateIntEnumShape(GenerateIntEnumDirective<DocGenerationContext, DocSettings> directive) {
+        var shape = directive.shape();
+        var intEnum = shape.asIntEnumShape().orElseThrow(() -> new ExpectationNotMetException(
+                "Expected an intEnum shape, but found " + shape, shape));
+        new StructuredShapeGenerator(directive.context()).accept(intEnum, MemberListingType.OPTIONS);
+    }
+
+    @Override
+    public void generateResource(GenerateResourceDirective<DocGenerationContext, DocSettings> directive) {
+        new ResourceGenerator().accept(directive.context(), directive.shape());
+    }
+}

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) {
+}