Skip to content

Commit 93586b0

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

File tree

28 files changed

+1457
-959
lines changed

28 files changed

+1457
-959
lines changed

.github/workflows/ci.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,11 @@ jobs:
3838
activate-environment: true
3939
enable-cache: true
4040

41+
- name: Install pandoc
42+
uses: pandoc/actions/setup@v1
43+
with:
44+
version: 3.8.2
45+
4146
- name: Setup workspace
4247
run: |
4348
make install

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/it/java/software/amazon/smithy/python/codegen/test/AwsCodegenTest.java

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
*/
55
package software.amazon.smithy.python.codegen.test;
66

7+
import static org.junit.jupiter.api.Assertions.assertTrue;
8+
9+
import java.nio.file.Files;
710
import java.nio.file.Path;
811
import org.junit.jupiter.api.Test;
912
import org.junit.jupiter.api.io.TempDir;
@@ -14,7 +17,8 @@
1417
import software.amazon.smithy.python.codegen.PythonClientCodegenPlugin;
1518

1619
/**
17-
* Simple test that executes the Python client codegen plugin for an AWS-like service.
20+
* Simple test that executes the Python client codegen plugin for an AWS-like service
21+
* and validates that MkDocs documentation files are generated.
1822
*/
1923
public class AwsCodegenTest {
2024

@@ -36,6 +40,20 @@ public void testCodegen(@TempDir Path tempDir) {
3640
.model(model)
3741
.build();
3842
plugin.execute(context);
43+
44+
// Verify MkDocs documentation files are generated for AWS services
45+
Path docsDir = tempDir.resolve("docs");
46+
assertTrue(Files.exists(docsDir), "docs directory should be created");
47+
48+
Path indexFile = docsDir.resolve("index.md");
49+
assertTrue(Files.exists(indexFile), "index.md should be generated for AWS services");
50+
51+
Path operationsDir = docsDir.resolve("operations");
52+
assertTrue(Files.exists(operationsDir), "operations directory should be created");
53+
54+
// Verify at least one operation file exists
55+
Path basicOperationFile = operationsDir.resolve("basic_operation.md");
56+
assertTrue(Files.exists(basicOperationFile), "basic_operation.md should be generated");
3957
}
4058

4159
}

0 commit comments

Comments
 (0)