fix(pacmak): examples with multi-line strings produce invalid python …

…docstrings

Since docstrings are now rendered inside single-quoted multiline strings to allow the docstring itself to include example code with double-quoted multiline string literals. Those are the ones produced by rosetta for python.

Fixes #2569

packages/jsii-calc/lib/documented.ts

@@ -6,6 +6,13 @@
  *
  * Multiple paragraphs are separated by an empty line.
  *
+ * @example
+ * const x = 12 + 44;
+ * const s1 = "string";
+ * const s2 = "string \nwith new newlines"; // see https://github.com/aws/jsii/issues/2569
+ * const s3 = `string
+ *             with
+ *             new lines`;
  * @stable
  */
 export class DocumentedClass {

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

@@ -42,6 +42,10 @@ const requirementsFile = path.resolve(
   'requirements-dev.txt',
 );
 
+// we use single-quotes for multi-line strings to allow examples within the
+// docstrings themselves to include double-quotes (see https://github.com/aws/jsii/issues/2569)
+const DOCSTRING_QUOTES = "'''";
+
 export default class Python extends Target {
   protected readonly generator: PythonGenerator;
 
@@ -1571,9 +1575,9 @@ class PythonModule implements PythonType {
       this.fqn === this.assembly.name &&
       this.package.convertedReadme.trim().length > 0
     ) {
-      code.line('"""');
+      code.line(DOCSTRING_QUOTES);
       code.line(this.package.convertedReadme);
-      code.line('"""');
+      code.line(DOCSTRING_QUOTES);
     }
   }
 
@@ -2189,16 +2193,16 @@ class PythonGenerator extends Generator {
     }
 
     if (lines.length === 1) {
-      code.line(`"""${lines[0]}"""`);
+      code.line(`${DOCSTRING_QUOTES}${lines[0]}${DOCSTRING_QUOTES}`);
     } else {
-      code.line(`"""${lines[0]}`);
+      code.line(`${DOCSTRING_QUOTES}${lines[0]}`);
       lines.splice(0, 1);
 
       for (const line of lines) {
         code.line(line);
       }
 
-      code.line('"""');
+      code.line(DOCSTRING_QUOTES);
     }
     if (options.trailingNewLine) {
       code.line();