feat(ruby): tidy rendered examples/READMEs (inline refs, HTML comments, requires)

Three display-layer fixes for translated docs prose:

- rubifyInlineRefs: translate inline `code` API references in prose to snake_case
  (`bucketArn` -> `bucket_arn`, `arnForObjects(pattern)` -> `arn_for_objects(pattern)`),
  matching the real member names. Literals/types/enums are left alone.
- Strip HTML comments (CDK's `<!--BEGIN STABILITY BANNER-->` / CFNONLY markers),
  which YARD's Markdown renderer would otherwise show as visible text.
- Strip `require` boilerplate from examples: it comes from the snippet fixture and,
  after import translation, collapses to duplicate `require 'aws-cdk-lib'` lines.
  Applied to @example (convertExample) and README/remarks fenced blocks.

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

Author: omarqureshi

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

@@ -166,6 +166,21 @@ interface MemberLike {
  * packages/@jsii/ruby-runtime-test/spec/unit/utils_spec.rb), so kernel
  * callbacks dispatch to the renamed member.
  */
+// A `require` / `require_relative` line in a rendered example. These come from the
+// snippet's fixture (import boilerplate) and are noise in the API docs — and after
+// import translation, several imports from one package collapse to duplicate
+// `require 'aws-cdk-lib'` lines. They're stripped before display.
+const REQUIRE_LINE = /^\s*require(?:_relative)?\s+['"][^'"]+['"];?\s*$/;
+
+/** Drop `require` lines from a standalone code snippet and any blank lines they leave. */
+function stripRequireLines(code: string): string {
+  return code
+    .split('\n')
+    .filter((line) => !REQUIRE_LINE.test(line))
+    .join('\n')
+    .replace(/^\s*\n+/, '');
+}
+
 const RUBY_RESERVED_NAMES = new Set([
   // Keywords
   'alias',
@@ -241,7 +256,7 @@ export class RubyGenerator extends Generator {
       TargetLanguage.RUBY,
       enforcesStrictMode(this.assembly),
     );
-    return translated.source;
+    return stripRequireLines(translated.source);
   }
 
   /**
@@ -252,12 +267,67 @@ export class RubyGenerator extends Generator {
    */
   private convertMarkdown(markdown: string, apiLocation: ApiLocation): string {
     assertSpecIsRosettaCompatible(this.assembly);
-    return this.rosetta.translateSnippetsInMarkdown(
+    // Strip HTML comments (e.g. CDK's `<!--BEGIN STABILITY BANNER-->` / CFNONLY
+    // markers): YARD's Markdown renderer emits them as visible text instead of hiding
+    // them, so they'd otherwise show up verbatim in the rendered README.
+    const cleaned = markdown.replace(/<!--[\s\S]*?-->/g, '');
+    const translated = this.rosetta.translateSnippetsInMarkdown(
       apiLocation,
-      markdown,
+      cleaned,
       TargetLanguage.RUBY,
       enforcesStrictMode(this.assembly),
     );
+    return this.rubifyInlineRefs(translated);
+  }
+
+  /**
+   * Rosetta translates fenced code blocks, but not inline `code` references in the
+   * prose (e.g. the `bucketArn` / `arnForObjects(pattern)` list in the S3 README).
+   * Rewrite those to Ruby: a bare camelCase identifier — optionally followed by a
+   * call's parentheses — becomes snake_case via the same `toSnakeCase` the member
+   * generator uses, so `bucketArn` -> `bucket_arn` and `arnForObjects(pattern)` ->
+   * `arn_for_objects(pattern)`. Everything else is left untouched: fenced blocks
+   * (already translated), and anything that isn't a bare identifier — ARNs, URLs and
+   * names (they carry `:` `/` `-` `.`), PascalCase type names, ALL_CAPS enum members.
+   */
+  private rubifyInlineRefs(markdown: string): string {
+    let inFence = false;
+    let fenceStarted = false; // seen real content since the fence opened
+    const out: string[] = [];
+    for (const line of markdown.split('\n')) {
+      if (/^\s*(```|~~~)/.test(line)) {
+        inFence = !inFence;
+        fenceStarted = false;
+        out.push(line);
+        continue;
+      }
+      if (inFence) {
+        // Drop `require` boilerplate from code samples, plus the leading blank lines
+        // it leaves at the top of a block.
+        if (REQUIRE_LINE.test(line)) {
+          continue;
+        }
+        if (!fenceStarted && line.trim() === '') {
+          continue;
+        }
+        fenceStarted = true;
+        out.push(line);
+        continue;
+      }
+      out.push(
+        line.replace(/`([^`\n]+)`/g, (whole, inner: string) => {
+          const m = /^([a-z][A-Za-z0-9]*)(\([A-Za-z0-9_,\s]*\))?$/.exec(inner);
+          if (!m || !/[A-Z]/.test(m[1])) {
+            return whole;
+          }
+          const call = m[2]
+            ? m[2].replace(/[A-Za-z][A-Za-z0-9]*/g, (arg) => toSnakeCase(arg))
+            : '';
+          return `\`${toSnakeCase(m[1])}${call}\``;
+        }),
+      );
+    }
+    return out.join('\n');
   }
 
   /**