chore(repo): enable rosetta for doc compilation

.projenrc.ts

@@ -137,6 +137,7 @@ const project = new awscdk.AwsCdkConstructLibrary({
     '!.ort.yml',
     '.idea',
     '.vscode',
+    '.jsii.tabl.json',
   ],
   stability: 'experimental',
   sampleCode: false,
@@ -369,11 +370,42 @@ project.addTask('generate-models-containers', {
   ],
 });
 
+// Add verification of documentation examples as a new task
+project.addTask('docs:compile', {
+  description: 'Verify documentation examples are correctly compiled',
+  steps: [
+    {
+      say: 'Synthesize project files',
+      spawn: 'default',
+    },
+    {
+      say: 'Pre-compile',
+      spawn: 'pre-compile',
+    },
+    {
+      say: 'Compile',
+      spawn: 'compile',
+    },
+    {
+      say: 'Verify documentation examples are correctly compiled',
+      exec: 'jsii-rosetta extract --strict',
+    },
+  ],
+});
+
 const postCompile = project.tasks.tryFind('post-compile');
 if (postCompile) {
   postCompile.exec(
     'npx typedoc --plugin typedoc-plugin-markdown --out apidocs --readme none --categoryOrder "Namespaces,Classes,Interfaces,*" --disableSources ./src/index.ts',
   );
 }
 
+// Add verification of documentation examples to the post-compile task
+// (we cannot add it to the build task since it's locked. We add it to post-compile instead which
+// is not locked and executed as part of the build task)
+project.tasks.tryFind('post-compile')?.insertStep(1, {
+  say: 'Verify documentation examples are correctly compiled',
+  exec: 'jsii-rosetta extract --strict',
+});
+
 project.synth();

DEVELOPER_GUIDE.md

@@ -51,7 +51,10 @@ npm install -g npm aws-cdk yarn projen
 
 ## Testing
 
-AWS Generative AI CDK Constructs use two types of testing: unit testing and integration testing. Unit testing targets specific aspects of a construct or one of the functions in the core library. The unit tests check that certain aspects of the results are correct. You can learn more about unit testing CDK constructs [here](https://docs.aws.amazon.com/cdk/latest/guide/testing.html) and [here](https://aws.amazon.com/blogs/developer/testing-infrastructure-with-the-aws-cloud-development-kit-cdk/).
+AWS Generative AI CDK Constructs use three types of testing: unit testing, integration testing and documentation testing. 
+
+- Unit testing targets specific aspects of a construct or one of the functions in the core library. The unit tests check that certain aspects of the results are correct. You can learn more about unit testing CDK constructs [here](https://docs.aws.amazon.com/cdk/latest/guide/testing.html) and [here](https://aws.amazon.com/blogs/developer/testing-infrastructure-with-the-aws-cloud-development-kit-cdk/).
+- Documentation tests are verifying that the code snippets present in the main README file compile. This prevents common issues where documentation examples become outdated or contain errors. For more information, please refer to the [DOCUMENTATION_TESTING](./DOCUMENTATION_TESTING.md) guide.
 
 All test files can be found in the /test directory under each construct (or core). You'll find two types of files in this directory:
 
@@ -69,10 +72,10 @@ All test files can be found in the /test directory under each construct (or core
 - Using the samples repository to test your locally changed constructs. This is also useful for development.
 
 ### Pre-req:
+
 - Download the samples repository (The official samples repository https://github.com/aws-samples/generative-ai-cdk-constructs-samples includes a collection of functional use case implementations to demonstrate the usage of AWS Generative AI CDK Constructs. These can be used in the same way as architectural patterns, and can be conceptualized as an additional "higher-level" abstraction of those patterns. Those patterns (constructs) are composed together into [stacks](https://docs.aws.amazon.com/cdk/latest/guide/stacks.html), forming a "CDK app".
 )
 
-
 ### Step 1: Building the Generative AI CDK Construct
 
 Navigate to the [Generative AI CDK Construct Repository] (https://github.com/aws-samples/generative-ai-cdk-constructs-samples):

DOCUMENTATION_TESTING.md

@@ -0,0 +1,100 @@
+# Documentation Guide
+
+This guide explains how to maintain and verify documentation for the AWS Generative AI CDK Constructs library.
+
+## Overview
+
+This project uses [jsii-rosetta](https://github.com/aws/jsii/tree/main/packages/jsii-rosetta) to ensure that all code examples in the documentation are syntactically correct and can be compiled. This prevents common issues where documentation examples become outdated or contain errors.
+
+## How It Works
+
+This library uses [jsii](https://aws.github.io/jsii/) make it polyglot. jsii allows code in any language to naturally interact with JavaScript classes. It is the technology that enables the AWS Cloud Development Kit to deliver polyglot libraries from a single codebase, like this one. A class library written in TypeScript can be used in projects authored in TypeScript or Javascript (as usual), but also in Python, Java, C# (and other languages from the .NET family), ...
+
+jsii first compiles the code written in Typescript using the standard typescript compiler (tsc) to produce the Javascript code. It then generates an [assembly file (.jsii)](https://aws.github.io/jsii/user-guides/language-support/assembly/), which is a JSON-formatted document. This file contains a lot of information about the constructs, their fields, methods and the documentation.
+
+jsii is a toolchain with multiple tools:
+
+- jsii-rosetta that transliterates code snippets (in docs) from TypeScript to target languages. We’ll come back to this one.
+- jsii-packmack generates libraries in different programming languages.
+- jsii-docgen generates the API.md file
+and more. All the tools are described in the [documentation](https://aws.github.io/jsii/overview/toolchain/)
+
+Specifically around the documentation, jsii-rosetta will use the generated assemble file (.jsii) to extract all the examples, compile them and transliterate (translate) them in all languages. If the compilation succeed, it will generate a tablet file (named .jsii.tabl.json) that will contain all the code snippets from your project in all languages.
+
+### 1. Rosetta Fixtures
+
+Rosetta fixtures are template files that provide the necessary imports and boilerplate code for examples. They are located in the `rosetta/` directory:
+
+- `default.ts-fixture`: Default template for most examples
+
+### 2. README Integration
+
+The README.md file uses special keywords to reference example files:
+
+```markdown
+typescript fixture=default
+```
+
+You can reference any fixture located in the fixture folder.
+
+## Adding New Examples
+
+### Step 1: Fixture
+
+Update the existing fixture file in the rosetta folder, or create a new one for your use case.
+
+### Step 2: Update the README
+
+References your fixture in the code snippet definition:
+
+```markdown
+typescript fixture=default
+```
+
+### Step 3: Test the Example
+
+Run the documentation verification:
+
+```bash
+yarn docs:compile
+```
+
+This will:
+
+1. Compile the TypeScript code
+2. Extract and verify all examples using jsii-rosetta
+3. Fail if any examples have compilation errors
+
+This step will also run as part of the full build (projen build).
+
+## Best Practices
+
+### 1. Keep Examples Simple
+
+Examples should demonstrate the most common use case for a construct. Complex scenarios can be documented separately.
+
+### 2. Use Appropriate Fixtures
+
+Choose the fixture that best matches your example:
+
+- Use `default.ts-fixture` for basic examples
+- Use specific fixtures (e.g., `special.ts-fixture`) for domain-specific examples
+
+### 4. Test Examples Regularly
+
+Run `projen docs:compile` before committing changes to ensure all examples compile correctly.
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Import Errors**: Make sure all necessary imports are included in your fixture file
+2. **Compilation Errors**: Check that your example code is syntactically correct
+3. **Missing Fixtures**: Create appropriate fixture files for new domains
+
+### Getting Help
+
+If you encounter issues with documentation verification:
+
+1. Check the jsii-rosetta documentation: https://github.com/aws/jsii/tree/main/packages/jsii-rosetta
+2. Review the fixture files in the `rosetta/` directory

apidocs/@cdklabs/namespaces/bedrock/classes/AgentBase.md

@@ -57,12 +57,6 @@ Contains methods and attributes valid for Agents either created with CDK or impo
 
 The ARN of the agent.
 
-#### Example
-
-```ts
-"arn:aws:bedrock:us-east-1:123456789012:agent/OKDSJOGKMO"
-```
-
 #### Attribute
 
 #### Implementation of
@@ -77,12 +71,6 @@ The ARN of the agent.
 
 The ID of the Agent.
 
-#### Example
-
-```ts
-"OKDSJOGKMO"
-```
-
 #### Attribute
 
 #### Implementation of

apidocs/@cdklabs/namespaces/bedrock/classes/ConfluenceDataSource.md

@@ -68,12 +68,6 @@ The Confluence host URL or instance URL.
 
 The unique identifier of the data source.
 
-#### Example
-
-```ts
-'JHUEVXUZMU'
-```
-
 #### Overrides
 
 [`DataSourceNew`](DataSourceNew.md).[`dataSourceId`](DataSourceNew.md#datasourceid)

apidocs/@cdklabs/namespaces/bedrock/classes/CrossRegionInferenceProfile.md

@@ -26,11 +26,7 @@ https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html
 
 > `readonly` **inferenceProfileArn**: `string`
 
-#### Example
-
-```ts
-'arn:aws:bedrock:us-east-1:123456789012:inference-profile/us.anthropic.claude-3-5-sonnet-20240620-v1:0'
-```
+Inference profile ARN
 
 #### Implementation of
 
@@ -42,11 +38,7 @@ https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html
 
 > `readonly` **inferenceProfileId**: `string`
 
-#### Example
-
-```ts
-'us.anthropic.claude-3-5-sonnet-20240620-v1:0'
-```
+Inference profile ID
 
 #### Implementation of
 
@@ -78,11 +70,7 @@ This equals to the inferenceProfileArn property, useful just to implement IInvok
 
 > `readonly` **type**: [`InferenceProfileType`](../enumerations/InferenceProfileType.md)
 
-#### Example
-
-```ts
-InferenceProfileType.SYSTEM_DEFINED
-```
+Inference profile type
 
 #### Implementation of
 

apidocs/@cdklabs/namespaces/bedrock/interfaces/AgentAttributes.md

@@ -16,12 +16,6 @@ Attributes for specifying an imported Bedrock Agent.
 
 The ARN of the agent.
 
-#### Example
-
-```ts
-"arn:aws:bedrock:us-east-1:123456789012:agent/OKDSJOGKMO"
-```
-
 #### Attribute
 
 ***
@@ -58,10 +52,4 @@ When this agent was last updated.
 
 The ARN of the IAM role associated to the agent.
 
-#### Example
-
-```ts
-"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-```
-
 #### Attribute

apidocs/@cdklabs/namespaces/bedrock/interfaces/ConfluenceCrawlingFilters.md

@@ -20,15 +20,6 @@ These filters allow you to include or exclude specific content based on object t
 - You can specify inclusion and exclusion patterns using regular expressions.
 - If both inclusion and exclusion patterns match a document, the exclusion takes precedence.
 
-## Example
-
-```ts
-{
- *   objectType: ConfluenceObjectType.ATTACHMENT,
- *   excludePatterns: [".*private.*\\.pdf"]
- * }
-```
-
 ## Properties
 
 ### excludePatterns?

apidocs/@cdklabs/namespaces/bedrock/interfaces/ConfluenceDataSourceAssociationProps.md

@@ -67,12 +67,6 @@ ChunkingStrategy.DEFAULT
 
 The Confluence host URL or instance URL.
 
-#### Example
-
-```ts
-https://example.atlassian.net
-```
-
 ***
 
 ### contextEnrichment?

apidocs/@cdklabs/namespaces/bedrock/interfaces/ConfluenceDataSourceProps.md

@@ -71,12 +71,6 @@ ChunkingStrategy.DEFAULT
 
 The Confluence host URL or instance URL.
 
-#### Example
-
-```ts
-https://example.atlassian.net
-```
-
 #### Inherited from
 
 [`ConfluenceDataSourceAssociationProps`](ConfluenceDataSourceAssociationProps.md).[`confluenceUrl`](ConfluenceDataSourceAssociationProps.md#confluenceurl)

apidocs/@cdklabs/namespaces/bedrock/interfaces/IAgent.md

@@ -20,12 +20,6 @@ Represents an Agent, either created with CDK or imported.
 
 The ARN of the agent.
 
-#### Example
-
-```ts
-"arn:aws:bedrock:us-east-1:123456789012:agent/OKDSJOGKMO"
-```
-
 #### Attribute
 
 ***
@@ -36,12 +30,6 @@ The ARN of the agent.
 
 The ID of the Agent.
 
-#### Example
-
-```ts
-"OKDSJOGKMO"
-```
-
 #### Attribute
 
 ***