-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
This adds and makes use of a snippet generator interface that lets other generators provide examples to be included in the docs. It's unfortunately more ugly than I'd like, notbably with config. Generators will essentially have to run much of their generator to be able to provide an accurate example, so we have to give a fake plugin context that they can use. The codegen director will need to be updated to make this more workable. This is just a proof of concept meant to show how it might work from the doc generator side.
- Loading branch information
1 parent
a850ad3
commit 9678934
Showing
10 changed files
with
322 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
73 changes: 73 additions & 0 deletions
73
...gen-core/src/main/java/software/amazon/smithy/docgen/core/MockPluginContextGenerator.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| /* | ||
| * 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.Optional; | ||
| import software.amazon.smithy.build.MockManifest; | ||
| import software.amazon.smithy.build.PluginContext; | ||
| import software.amazon.smithy.build.model.ProjectionConfig; | ||
| import software.amazon.smithy.model.Model; | ||
| import software.amazon.smithy.model.node.Node; | ||
| import software.amazon.smithy.model.node.ObjectNode; | ||
| import software.amazon.smithy.utils.SmithyUnstableApi; | ||
|
|
||
| /** | ||
| * Generates mock plugin contexts to pass along to snippet generators. | ||
| */ | ||
| @SmithyUnstableApi | ||
| class MockPluginContextGenerator { | ||
| private final PluginContext baseContext; | ||
| private final ObjectNode pluginSettings; | ||
|
|
||
| /** | ||
| * Constructs a MockPluginContextGenerator. | ||
| * | ||
| * @param baseContext The context to base plugin context generation on. | ||
| * @param pluginSettings Settings specifically given to pass to plugins via the doc generator. | ||
| */ | ||
| MockPluginContextGenerator(PluginContext baseContext, ObjectNode pluginSettings) { | ||
| if (baseContext.getProjection().isEmpty()) { | ||
| // PluginContext will NPE if there's no projection config so you have to do it manually | ||
| // until that gets fixed. | ||
| var builder = PluginContext.builder() | ||
| .projection(baseContext.getProjectionName(), ProjectionConfig.builder().build()) | ||
| .model(baseContext.getModel()) | ||
| .originalModel(baseContext.getOriginalModel().orElse(baseContext.getModel())) | ||
| .events(baseContext.getEvents()) | ||
| .settings(baseContext.getSettings()) | ||
| .fileManifest(baseContext.getFileManifest()) | ||
| .sources(baseContext.getSources()); | ||
| baseContext.getPluginClassLoader().ifPresent(builder::pluginClassLoader); | ||
| baseContext.getOriginalModel().ifPresent(builder::originalModel); | ||
| baseContext.getArtifactName().ifPresent(builder::artifactName); | ||
| baseContext = builder.build(); | ||
| } | ||
| this.baseContext = baseContext; | ||
| this.pluginSettings = pluginSettings; | ||
| } | ||
|
|
||
| /** | ||
| * Create a new plugin context with the given model and plugin name. | ||
| * | ||
| * @param model The version of the model to hand to the plugin. | ||
| * @param pluginName The name of the plugin. This is used to search for existing config. | ||
| * @return Returns a plugin context with the given model and config for the named plugin. | ||
| */ | ||
| PluginContext getStubbedContext(Model model, String pluginName) { | ||
| ObjectNode settings = pluginSettings.getObjectMember(pluginName) | ||
| .or(() -> baseContext.getProjection() | ||
| .map(ProjectionConfig::getPlugins) | ||
| .flatMap(plugins -> Optional.ofNullable(plugins.get(pluginName)))) | ||
| .orElse(Node.objectNode()); | ||
|
|
||
| return baseContext.toBuilder() | ||
| .fileManifest(new MockManifest()) | ||
| .artifactName(pluginName) | ||
| .model(model) | ||
| .settings(settings) | ||
| .build(); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
43 changes: 43 additions & 0 deletions
43
...re/src/main/java/software/amazon/smithy/docgen/core/generators/ExampleInputGenerator.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
|
|
||
| package software.amazon.smithy.docgen.core.generators; | ||
|
|
||
| import software.amazon.smithy.model.node.Node; | ||
| import software.amazon.smithy.model.shapes.OperationShape; | ||
| import software.amazon.smithy.model.shapes.Shape; | ||
| import software.amazon.smithy.model.traits.ExamplesTrait.Example; | ||
|
|
||
| public class ExampleInputGenerator implements SnippetGenerator { | ||
| @Override | ||
| public String name() { | ||
| return "input"; | ||
| } | ||
|
|
||
| @Override | ||
| public boolean isWireProtocolGenerator() { | ||
| return true; | ||
| } | ||
|
|
||
| @Override | ||
| public String tabTitle() { | ||
| return "Input"; | ||
| } | ||
|
|
||
| @Override | ||
| public String language() { | ||
| return "json"; | ||
| } | ||
|
|
||
| @Override | ||
| public String generateShapeSnippet(Shape shape, Node value) { | ||
| return ""; | ||
| } | ||
|
|
||
| @Override | ||
| public String generateExampleSnippet(OperationShape operation, Example example) { | ||
| return Node.prettyPrintJson(example.getInput()); | ||
| } | ||
| } |
38 changes: 38 additions & 0 deletions
38
...e/src/main/java/software/amazon/smithy/docgen/core/generators/ExampleOutputGenerator.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
|
|
||
| package software.amazon.smithy.docgen.core.generators; | ||
|
|
||
| import software.amazon.smithy.model.node.Node; | ||
| import software.amazon.smithy.model.shapes.OperationShape; | ||
| import software.amazon.smithy.model.shapes.Shape; | ||
| import software.amazon.smithy.model.traits.ExamplesTrait.Example; | ||
|
|
||
| public class ExampleOutputGenerator implements SnippetGenerator { | ||
| @Override | ||
| public String name() { | ||
| return "output"; | ||
| } | ||
|
|
||
| @Override | ||
| public String tabTitle() { | ||
| return "Output"; | ||
| } | ||
|
|
||
| @Override | ||
| public String language() { | ||
| return "json"; | ||
| } | ||
|
|
||
| @Override | ||
| public String generateShapeSnippet(Shape shape, Node value) { | ||
| return ""; | ||
| } | ||
|
|
||
| @Override | ||
| public String generateExampleSnippet(OperationShape operation, Example example) { | ||
| return Node.prettyPrintJson(example.getOutput().orElse(Node.objectNode())); | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.