Replace Sphinx doc gen with MkDocs and Markdown

.github/workflows/ci.yml

@@ -38,6 +38,11 @@ jobs:
           activate-environment: true
           enable-cache: true
 
+      - name: Install pandoc
+        uses: pandoc/actions/setup@v1
+        with:
+          version: 3.8.2
+
       - name: Setup workspace
         run: |
           make install

README.md

@@ -112,12 +112,13 @@ With both files your project directory should look like this:
 
 The code generator libraries have not been published yet, so
 you'll need to build it yourself. To build and run the generator, you will need
-the following prerequisites:
+the following prerequisites installed in your environment:
 
 * [uv](https://docs.astral.sh/uv/)
 * The [Smithy CLI](https://smithy.io/2.0/guides/smithy-cli/cli_installation.html)
 * JDK 17 or newer
 * make
+* [pandoc](https://pandoc.org/installing.html) CLI
 
 This project uses [uv](https://docs.astral.sh/uv/) for managing all things python.
 Once you have it installed, run the following command to check that it's ready to use:
@@ -169,6 +170,12 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+#### pandoc CLI
+
+The code generator uses [pandoc](https://pandoc.org/) to convert documentation from Smithy models
+into Markdown format for Python docstrings, which can then be used to generate 
+documentation with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/getting-started/).
+
 #### Is Java really required?
 
 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

@@ -4,6 +4,9 @@
  */
 package software.amazon.smithy.python.codegen.test;
 
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.nio.file.Files;
 import java.nio.file.Path;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
@@ -14,7 +17,8 @@
 import software.amazon.smithy.python.codegen.PythonClientCodegenPlugin;
 
 /**
- * Simple test that executes the Python client codegen plugin for an AWS-like service.
+ * Simple test that executes the Python client codegen plugin for an AWS-like service
+ * and validates that MkDocs documentation files are generated.
  */
 public class AwsCodegenTest {
 
@@ -36,6 +40,20 @@ public void testCodegen(@TempDir Path tempDir) {
                 .model(model)
                 .build();
         plugin.execute(context);
+
+        // Verify MkDocs documentation files are generated for AWS services
+        Path docsDir = tempDir.resolve("docs");
+        assertTrue(Files.exists(docsDir), "docs directory should be created");
+
+        Path indexFile = docsDir.resolve("index.md");
+        assertTrue(Files.exists(indexFile), "index.md should be generated for AWS services");
+
+        Path operationsDir = docsDir.resolve("operations");
+        assertTrue(Files.exists(operationsDir), "operations directory should be created");
+
+        // Verify at least one operation file exists
+        Path basicOperationFile = operationsDir.resolve("basic_operation.md");
+        assertTrue(Files.exists(basicOperationFile), "basic_operation.md should be generated");
     }
 
 }