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

…docstrings (#2571)

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



---

By submitting this pull request, I confirm that my contribution is made under the terms of the [Apache 2.0 license].

[Apache 2.0 license]: https://www.apache.org/licenses/LICENSE-2.0

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-calc/test/assembly.jsii

@@ -4144,6 +4144,7 @@
     "jsii-calc.DocumentedClass": {
       "assembly": "jsii-calc",
       "docs": {
+        "example": "const x = 12 + 44;\nconst s1 = \"string\";\nconst s2 = \"string \\nwith new newlines\"; // see https://github.com/aws/jsii/issues/2569\nconst s3 = `string\n            with\n            new lines`;",
         "remarks": "This is the meat of the TSDoc comment. It may contain\nmultiple lines and multiple paragraphs.\n\nMultiple paragraphs are separated by an empty line.",
         "stability": "stable",
         "summary": "Here's the first line of the TSDoc comment."
@@ -4157,7 +4158,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/documented.ts",
-        "line": 11
+        "line": 18
       },
       "methods": [
         {
@@ -4169,7 +4170,7 @@
           },
           "locationInModule": {
             "filename": "lib/documented.ts",
-            "line": 21
+            "line": 28
           },
           "name": "greet",
           "parameters": [
@@ -4197,7 +4198,7 @@
           },
           "locationInModule": {
             "filename": "lib/documented.ts",
-            "line": 31
+            "line": 38
           },
           "name": "hola"
         }
@@ -5239,7 +5240,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "lib/documented.ts",
-        "line": 39
+        "line": 46
       },
       "name": "Greetee",
       "properties": [
@@ -5253,7 +5254,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "lib/documented.ts",
-            "line": 45
+            "line": 52
           },
           "name": "name",
           "optional": true,
@@ -9391,7 +9392,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "lib/documented.ts",
-        "line": 54
+        "line": 61
       },
       "methods": [
         {
@@ -9401,7 +9402,7 @@
           },
           "locationInModule": {
             "filename": "lib/documented.ts",
-            "line": 58
+            "line": 65
           },
           "name": "doAThing"
         }
@@ -14440,5 +14441,5 @@
     }
   },
   "version": "3.20.120",
-  "fingerprint": "Qv5CJVZ6t7cfQmCSHOLrbefAuLKX9JUbhUCSh+mD+po="
+  "fingerprint": "DELAKIDgUwCEVXhZflQBdllcDRnscledlYW0UXrjzbM="
 }

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();