feat(ruby): emit submodule READMEs as module docstrings

Mirror the Python target's emitModuleDocumentation: for the assembly and
each submodule that has a README, translate its TypeScript samples to Ruby
via Rosetta (translateSnippetsInMarkdown, same tablet path as @example) and
emit the result as the module's YARD docstring in a doc-only `_readme.rb`
inside the module's directory, so YARD renders it on the module page.

This surfaces CDK's real usage docs — which live in module READMEs, not
per-type @example tags — in the Ruby API reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: omarqureshi

packages/jsii-pacmak/lib/targets/ruby.ts

@@ -244,6 +244,22 @@ export class RubyGenerator extends Generator {
     return translated.source;
   }
 
+  /**
+   * Translate the TypeScript code samples embedded in a Markdown document (a
+   * module README) into Ruby via Rosetta, leaving the prose untouched.  Mirror
+   * of `convertExample` but for whole documents, matching the Python target's
+   * `convertMarkdown`.
+   */
+  private convertMarkdown(markdown: string, apiLocation: ApiLocation): string {
+    assertSpecIsRosettaCompatible(this.assembly);
+    return this.rosetta.translateSnippetsInMarkdown(
+      apiLocation,
+      markdown,
+      TargetLanguage.RUBY,
+      enforcesStrictMode(this.assembly),
+    );
+  }
+
   /**
    * Normalize a type reference to its raw `spec.TypeReference` shape.
    * Call sites hold two shapes: jsii-reflect `TypeReference` instances
@@ -653,6 +669,10 @@ export class RubyGenerator extends Generator {
       this.code.closeFile(typeFile);
     }
 
+    // Emit each submodule's README as its module docstring (samples translated
+    // to Ruby), so YARD renders it on the module page.
+    this.emitModuleReadmes();
+
     // Generate the gemspec manifest file for package management
     await this.generateGemspec(outdir);
 
@@ -663,6 +683,45 @@ export class RubyGenerator extends Generator {
     return super.save(outdir, tarball, legalese);
   }
 
+  /**
+   * Emit each submodule's (and the assembly's own) README as a Ruby module
+   * docstring, its TypeScript samples translated to Ruby — mirroring the Python
+   * target's `emitModuleDocumentation`.  Each README goes in a doc-only
+   * `_readme.rb` inside the module's directory (alongside its type files) so a
+   * per-directory YARD run picks it up and renders it on the module page.  The
+   * file is never `require`d at runtime.
+   */
+  private emitModuleReadmes(): void {
+    const emit = (moduleFqn: string, markdown: string | undefined): void => {
+      if (!markdown) {
+        return;
+      }
+      const rubyModule = this.rubyFullTypeName(moduleFqn);
+      const translated = this.convertMarkdown(markdown, {
+        api: 'moduleReadme',
+        moduleFqn,
+      });
+      const docFile = path.join(
+        'lib',
+        this.rubyRequirePath(moduleFqn),
+        '_readme.rb',
+      );
+      this.code.openFile(docFile);
+      for (const line of translated.split('\n')) {
+        this.code.line(line.length > 0 ? `# ${line}` : '#');
+      }
+      this.code.line(`module ${rubyModule}; end`);
+      this.code.closeFile(docFile);
+    };
+
+    emit(this.assembly.name, this.assembly.readme?.markdown);
+    for (const [fqn, submodule] of Object.entries(
+      this.assembly.submodules ?? {},
+    )) {
+      emit(fqn, submodule.readme?.markdown);
+    }
+  }
+
   private emitHeader(): void {
     this.code.line("require 'jsii'");
     this.code.line("require 'json'");