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

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