Skip to content

Commit e056f72

Browse files
committed
Replace Sphinx doc gen with MkDocs and Markdown
1 parent d2fef49 commit e056f72

File tree

18 files changed

+974
-940
lines changed

18 files changed

+974
-940
lines changed

README.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,12 +112,13 @@ With both files your project directory should look like this:
112112

113113
The code generator libraries have not been published yet, so
114114
you'll need to build it yourself. To build and run the generator, you will need
115-
the following prerequisites:
115+
the following prerequisites installed in your environment:
116116

117117
* [uv](https://docs.astral.sh/uv/)
118118
* The [Smithy CLI](https://smithy.io/2.0/guides/smithy-cli/cli_installation.html)
119119
* JDK 17 or newer
120120
* make
121+
* [pandoc](https://pandoc.org/installing.html) CLI
121122

122123
This project uses [uv](https://docs.astral.sh/uv/) for managing all things python.
123124
Once you have it installed, run the following command to check that it's ready to use:
@@ -169,6 +170,12 @@ if __name__ == "__main__":
169170
asyncio.run(main())
170171
```
171172

173+
#### pandoc CLI
174+
175+
The code generator uses [pandoc](https://pandoc.org/) to convert documentation from Smithy models
176+
into Markdown format for Python docstrings, which can then be used to generate
177+
documentation with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/getting-started/).
178+
172179
#### Is Java really required?
173180

174181
Only for now. Once the generator has been published, the Smithy CLI will be able

codegen/aws/core/src/main/java/software/amazon/smithy/python/aws/codegen/AwsMkDocsFileGenerator.java

Lines changed: 516 additions & 0 deletions
Large diffs are not rendered by default.

codegen/aws/core/src/main/java/software/amazon/smithy/python/aws/codegen/AwsRstDocFileGenerator.java

Lines changed: 0 additions & 200 deletions
This file was deleted.

codegen/aws/core/src/main/resources/META-INF/services/software.amazon.smithy.python.codegen.integrations.PythonIntegration

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,4 @@ software.amazon.smithy.python.aws.codegen.AwsProtocolsIntegration
88
software.amazon.smithy.python.aws.codegen.AwsServiceIdIntegration
99
software.amazon.smithy.python.aws.codegen.AwsUserAgentIntegration
1010
software.amazon.smithy.python.aws.codegen.AwsStandardRegionalEndpointsIntegration
11-
software.amazon.smithy.python.aws.codegen.AwsRstDocFileGenerator
11+
software.amazon.smithy.python.aws.codegen.AwsMkDocsFileGenerator

codegen/aws/core/src/test/java/software/amazon/smithy/python/aws/codegen/MarkdownToRstDocConverterTest.java

Lines changed: 0 additions & 118 deletions
This file was deleted.

0 commit comments

Comments
 (0)