generated from amazon-archives/__template_Apache-2.0
-
Notifications
You must be signed in to change notification settings - Fork 24
Add sphinx doc generation #418
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
7d85d74
Initial commit
SamRemis 5ad44ff
Add RST file generation, RST linewrapping, and whitespace fixes
SamRemis 3c637c6
Run linter, minor fixes
SamRemis 1a36552
Fix linewrapping, add tests
SamRemis 2eab1a8
remove global dependencies on sphinx and pydata
SamRemis eb0f27b
Fix linewrapping issue
SamRemis cf9e9ec
Updates based on PR feedback
SamRemis fb551e2
Update codegen/core/src/main/java/software/amazon/smithy/python/codeg…
SamRemis 7abe2ce
Merge branch 'develop' into convert-docs-to-rst
SamRemis 169c988
Update libs.versions.toml
SamRemis 12f66d8
variable fix
SamRemis 25f2bd4
Update MarkdownToRstDocConverterTest.java
SamRemis File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
200 changes: 200 additions & 0 deletions
200
.../core/src/main/java/software/amazon/smithy/python/aws/codegen/AwsRstDocFileGenerator.java
This file contains hidden or 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,200 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
| package software.amazon.smithy.python.aws.codegen; | ||
|
|
||
| import static software.amazon.smithy.python.codegen.SymbolProperties.OPERATION_METHOD; | ||
|
|
||
| import java.util.List; | ||
| import software.amazon.smithy.model.traits.InputTrait; | ||
| import software.amazon.smithy.model.traits.OutputTrait; | ||
| import software.amazon.smithy.python.codegen.GenerationContext; | ||
| import software.amazon.smithy.python.codegen.integrations.PythonIntegration; | ||
| import software.amazon.smithy.python.codegen.sections.*; | ||
| import software.amazon.smithy.python.codegen.writer.PythonWriter; | ||
| import software.amazon.smithy.utils.CodeInterceptor; | ||
| import software.amazon.smithy.utils.CodeSection; | ||
|
|
||
| public class AwsRstDocFileGenerator implements PythonIntegration { | ||
|
|
||
| @Override | ||
| public List<? extends CodeInterceptor<? extends CodeSection, PythonWriter>> interceptors( | ||
| GenerationContext context | ||
| ) { | ||
| return List.of( | ||
| // We generate custom RST files for each member that we want to have | ||
| // its own page. This gives us much more fine-grained control of | ||
| // what gets generated than just using automodule or autoclass on | ||
| // the client would alone. | ||
| new OperationGenerationInterceptor(context), | ||
| new StructureGenerationInterceptor(context), | ||
| new ErrorGenerationInterceptor(context), | ||
| new UnionGenerationInterceptor(context), | ||
| new UnionMemberGenerationInterceptor(context)); | ||
| } | ||
|
|
||
| /** | ||
| * Utility method to generate a header for documentation files. | ||
| * | ||
| * @param title The title of the section. | ||
| * @return A formatted header string. | ||
| */ | ||
| private static String generateHeader(String title) { | ||
| return String.format("%s%n%s%n%n", title, "=".repeat(title.length())); | ||
| } | ||
|
|
||
| private static final class OperationGenerationInterceptor | ||
| implements CodeInterceptor.Appender<OperationSection, PythonWriter> { | ||
|
|
||
| private final GenerationContext context; | ||
|
|
||
| public OperationGenerationInterceptor(GenerationContext context) { | ||
| this.context = context; | ||
| } | ||
|
|
||
| @Override | ||
| public Class<OperationSection> sectionType() { | ||
| return OperationSection.class; | ||
| } | ||
|
|
||
| @Override | ||
| public void append(PythonWriter pythonWriter, OperationSection section) { | ||
| var operation = section.operation(); | ||
| var operationSymbol = context.symbolProvider().toSymbol(operation).expectProperty(OPERATION_METHOD); | ||
| var input = context.model().expectShape(operation.getInputShape()); | ||
| var inputSymbol = context.symbolProvider().toSymbol(input); | ||
| var output = context.model().expectShape(operation.getOutputShape()); | ||
| var outputSymbol = context.symbolProvider().toSymbol(output); | ||
|
|
||
| String operationName = operationSymbol.getName(); | ||
| String inputSymbolName = inputSymbol.toString(); | ||
| String outputSymbolName = outputSymbol.toString(); | ||
| String serviceName = context.symbolProvider().toSymbol(section.service()).getName(); | ||
| String docsFileName = String.format("docs/client/%s.rst", operationName); | ||
| String fullOperationReference = String.format("%s.client.%s.%s", | ||
| context.settings().moduleName(), | ||
| serviceName, | ||
| operationName); | ||
|
|
||
| context.writerDelegator().useFileWriter(docsFileName, "", fileWriter -> { | ||
| fileWriter.write(generateHeader(operationName)); | ||
| fileWriter.write(".. automethod:: " + fullOperationReference + "\n\n"); | ||
| fileWriter.write(".. toctree::\n :hidden:\n :maxdepth: 2\n\n"); | ||
| fileWriter.write("=================\nInput:\n=================\n\n"); | ||
| fileWriter.write(".. autoclass:: " + inputSymbolName + "\n :members:\n"); | ||
| fileWriter.write("=================\nOutput:\n=================\n\n"); | ||
| fileWriter.write(".. autoclass:: " + outputSymbolName + "\n :members:\n"); | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| private static final class StructureGenerationInterceptor | ||
| implements CodeInterceptor.Appender<StructureSection, PythonWriter> { | ||
|
|
||
| private final GenerationContext context; | ||
|
|
||
| public StructureGenerationInterceptor(GenerationContext context) { | ||
| this.context = context; | ||
| } | ||
|
|
||
| @Override | ||
| public Class<StructureSection> sectionType() { | ||
| return StructureSection.class; | ||
| } | ||
|
|
||
| @Override | ||
| public void append(PythonWriter pythonWriter, StructureSection section) { | ||
| var shape = section.structure(); | ||
| var symbol = context.symbolProvider().toSymbol(shape); | ||
| String docsFileName = String.format("docs/models/%s.rst", | ||
| symbol.getName()); | ||
| if (!shape.hasTrait(InputTrait.class) && !shape.hasTrait(OutputTrait.class)) { | ||
| context.writerDelegator().useFileWriter(docsFileName, "", writer -> { | ||
| writer.write(generateHeader(symbol.getName())); | ||
| writer.write(".. autoclass:: " + symbol.toString() + "\n :members:\n"); | ||
| }); | ||
| } | ||
| } | ||
| } | ||
|
|
||
| private static final class ErrorGenerationInterceptor | ||
| implements CodeInterceptor.Appender<ErrorSection, PythonWriter> { | ||
|
|
||
| private final GenerationContext context; | ||
|
|
||
| public ErrorGenerationInterceptor(GenerationContext context) { | ||
| this.context = context; | ||
| } | ||
|
|
||
| @Override | ||
| public Class<ErrorSection> sectionType() { | ||
| return ErrorSection.class; | ||
| } | ||
|
|
||
| @Override | ||
| public void append(PythonWriter pythonWriter, ErrorSection section) { | ||
| var symbol = section.errorSymbol(); | ||
| String docsFileName = String.format("docs/models/%s.rst", | ||
| symbol.getName()); | ||
| context.writerDelegator().useFileWriter(docsFileName, "", writer -> { | ||
| writer.write(generateHeader(symbol.getName())); | ||
| writer.write(".. autoexception:: " + symbol.toString() + "\n :members:\n :show-inheritance:\n"); | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| private static final class UnionGenerationInterceptor | ||
| implements CodeInterceptor.Appender<UnionSection, PythonWriter> { | ||
|
|
||
| private final GenerationContext context; | ||
|
|
||
| public UnionGenerationInterceptor(GenerationContext context) { | ||
| this.context = context; | ||
| } | ||
|
|
||
| @Override | ||
| public Class<UnionSection> sectionType() { | ||
| return UnionSection.class; | ||
| } | ||
|
|
||
| @Override | ||
| public void append(PythonWriter pythonWriter, UnionSection section) { | ||
| String parentName = section.parentName(); | ||
| String docsFileName = String.format("docs/models/%s.rst", parentName); | ||
| context.writerDelegator().useFileWriter(docsFileName, "", writer -> { | ||
| writer.write(".. _" + parentName + ":\n\n"); | ||
| writer.write(generateHeader(parentName)); | ||
| writer.write( | ||
| ".. autodata:: " + context.symbolProvider().toSymbol(section.unionShape()).toString() + " \n"); | ||
| }); | ||
| } | ||
| } | ||
|
|
||
| private static final class UnionMemberGenerationInterceptor | ||
| implements CodeInterceptor.Appender<UnionMemberSection, PythonWriter> { | ||
|
|
||
| private final GenerationContext context; | ||
|
|
||
| public UnionMemberGenerationInterceptor(GenerationContext context) { | ||
| this.context = context; | ||
| } | ||
|
|
||
| @Override | ||
| public Class<UnionMemberSection> sectionType() { | ||
| return UnionMemberSection.class; | ||
| } | ||
|
|
||
| @Override | ||
| public void append(PythonWriter pythonWriter, UnionMemberSection section) { | ||
| var memberSymbol = section.memberSymbol(); | ||
| String symbolName = memberSymbol.getName(); | ||
| String docsFileName = String.format("docs/models/%s.rst", symbolName); | ||
| context.writerDelegator().useFileWriter(docsFileName, "", writer -> { | ||
| writer.write(".. _" + symbolName + ":\n\n"); | ||
| writer.write(generateHeader(symbolName)); | ||
| writer.write(".. autoclass:: " + memberSymbol.toString() + " \n"); | ||
| }); | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or 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
109 changes: 109 additions & 0 deletions
109
...rc/test/java/software/amazon/smithy/python/aws/codegen/MarkdownToRstDocConverterTest.java
This file contains hidden or 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,109 @@ | ||
| /* | ||
| * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
| * SPDX-License-Identifier: Apache-2.0 | ||
| */ | ||
| package software.amazon.smithy.python.aws.codegen; | ||
|
|
||
| import static org.junit.jupiter.api.Assertions.assertEquals; | ||
|
|
||
| import org.junit.jupiter.api.BeforeEach; | ||
| import org.junit.jupiter.api.Test; | ||
| import software.amazon.smithy.python.codegen.writer.MarkdownToRstDocConverter; | ||
|
|
||
| public class MarkdownToRstDocConverterTest { | ||
|
|
||
| private MarkdownToRstDocConverter markdownToRstDocConverter; | ||
|
|
||
| @BeforeEach | ||
| public void setUp() { | ||
| markdownToRstDocConverter = MarkdownToRstDocConverter.getInstance(); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithTitleAndParagraph() { | ||
| String html = "<html><body><h1>Title</h1><p>Paragraph</p></body></html>"; | ||
| String expected = "\n\nTitle\n=====\nParagraph\n"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithImportantNote() { | ||
| String html = "<html><body><important>Important note</important></body></html>"; | ||
| String expected = "\n\n.. important::\n Important note\n"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithList() { | ||
| String html = "<html><body><ul><li>Item 1</li><li>Item 2</li></ul></body></html>"; | ||
| String expected = "\n\n* Item 1\n\n* Item 2\n\n"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithMixedElements() { | ||
| String html = "<html><body><h1>Title</h1><p>Paragraph</p><ul><li>Item 1</li><li>Item 2</li></ul></body></html>"; | ||
| String expected = "\n\nTitle\n=====\nParagraph\n\n* Item 1\n\n* Item 2\n\n"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithNestedElements() { | ||
| String html = "<html><body><h1>Title</h1><p>Paragraph with <strong>bold</strong> text</p></body></html>"; | ||
| String expected = "\n\nTitle\n=====\nParagraph with **bold** text\n"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithAnchorTag() { | ||
| String html = "<html><body><a href='https://example.com'>Link</a></body></html>"; | ||
| String expected = "\n`Link <https://example.com>`_"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithBoldTag() { | ||
| String html = "<html><body><b>Bold text</b></body></html>"; | ||
| String expected = "\n**Bold text**"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithItalicTag() { | ||
| String html = "<html><body><i>Italic text</i></body></html>"; | ||
| String expected = "\n*Italic text*"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithCodeTag() { | ||
| String html = "<html><body><code>code snippet</code></body></html>"; | ||
| String expected = "\n``code snippet``"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithNoteTag() { | ||
| String html = "<html><body><note>Note text</note></body></html>"; | ||
| String expected = "\n\n.. note::\n Note text\n"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
|
|
||
| @Test | ||
| public void testConvertCommonmarkToRstWithNestedList() { | ||
| String html = "<html><body><ul><li>Item 1<ul><li>Subitem 1</li></ul></li><li>Item 2</li></ul></body></html>"; | ||
| String expected = "\n\n* Item 1\n * Subitem 1\n\n* Item 2\n\n"; | ||
| String result = markdownToRstDocConverter.convertCommonmarkToRst(html); | ||
| assertEquals(expected, result); | ||
| } | ||
| } |
This file contains hidden or 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 hidden or 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.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What's the advantage of doing this over just autoclassing the client itself?