feat(pacmak): put translated README into module docstring (#900)

We put in all this effort to convert code samples from TypeScript
to Python, but they only were written in translated form to a README
file that was used to publish to PyPI. When the packages are installed
to a Python library directory, the README is gone (and so cannot be used
by Sphinx to insert into the docs).

Our own Sphinx generator was reading the README from the jsii assembly,
but that README still contains the TypeScript examples.

Insert the README content as a module-level docstrings so that the doc
generator can read the right translated README version and put it in the
docs. We keep the module docstring in MarkDown, not convert it to ReST,
since our ReST conversion is not very reliable yet.

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

@@ -952,6 +952,7 @@ interface ModuleOpts {
   assembly: spec.Assembly;
   assemblyFilename: string;
   loadAssembly: boolean;
+  package?: Package;
 }
 
 class Module implements PythonType {
@@ -963,6 +964,7 @@ class Module implements PythonType {
   private readonly assemblyFilename: string;
   private readonly loadAssembly: boolean;
   private readonly members: PythonBase[];
+  private readonly package?: Package;
 
   public constructor(name: string, fqn: string | null, opts: ModuleOpts) {
     this.pythonName = name;
@@ -971,6 +973,7 @@ class Module implements PythonType {
     this.assembly = opts.assembly;
     this.assemblyFilename = opts.assemblyFilename;
     this.loadAssembly = opts.loadAssembly;
+    this.package = opts.package;
     this.members = [];
   }
 
@@ -979,6 +982,8 @@ class Module implements PythonType {
   }
 
   public emit(code: CodeMaker, resolver: TypeResolver) {
+    this.emitModuleDocumentation(code);
+
     resolver = this.fqn ? resolver.bind(this.fqn, this.pythonName) : resolver;
 
     // Before we write anything else, we need to write out our module headers, this
@@ -1026,6 +1031,14 @@ class Module implements PythonType {
     code.line('publication.publish()');
   }
 
+  private emitModuleDocumentation(code: CodeMaker) {
+    if (this.package) {
+      code.line('"""');
+      code.line(this.package.convertedReadme);
+      code.line('"""');
+    }
+  }
+
   private emitDependencyImports(code: CodeMaker, _resolver: TypeResolver) {
     const deps = Array.from(
       new Set([
@@ -1053,6 +1066,7 @@ interface PackageData {
 }
 
 class Package {
+  public convertedReadme = '';
 
   public readonly name: string;
   public readonly version: string;
@@ -1083,6 +1097,11 @@ class Package {
   }
 
   public write(code: CodeMaker, resolver: TypeResolver) {
+    if (this.metadata.readme) {
+      // Conversion is expensive, so cache the result in a variable (we need it twice)
+      this.convertedReadme = convertSnippetsInMarkdown(this.metadata.readme.markdown, 'README.md').trim();
+    }
+
     const modules = [...this.modules.values()].sort((a, b) => a.pythonName.localeCompare(b.pythonName));
 
     // Iterate over all of our modules, and write them out to disk.
@@ -1130,9 +1149,7 @@ class Package {
     }
 
     code.openFile('README.md');
-    if (this.metadata.readme) {
-      code.line(convertSnippetsInMarkdown(this.metadata.readme.markdown, 'README.md'));
-    }
+    code.line(this.convertedReadme);
     code.closeFile('README.md');
 
     // Strip " (build abcdef)" from the jsii version
@@ -1455,7 +1472,9 @@ class PythonGenerator extends Generator {
       null,
       { assembly: assm,
         assemblyFilename: this.getAssemblyFileName(),
-        loadAssembly: false },
+        loadAssembly: false,
+        package: this.package
+      },
     );
 
     this.package.addModule(assemblyModule);

packages/jsii-pacmak/test/expected.jsii-calc-base/python/README.md

@@ -0,0 +1 @@
+

packages/jsii-pacmak/test/expected.jsii-calc-base/python/src/scope/jsii_calc_base/_jsii/__init__.py

@@ -1,3 +1,6 @@
+"""
+
+"""
 import abc
 import datetime
 import enum

packages/jsii-pacmak/test/expected.jsii-calc-lib/python/README.md

@@ -0,0 +1 @@
+

packages/jsii-pacmak/test/expected.jsii-calc-lib/python/src/scope/jsii_calc_lib/_jsii/__init__.py

@@ -1,3 +1,6 @@
+"""
+
+"""
 import abc
 import datetime
 import enum

packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/_jsii/__init__.py

@@ -1,3 +1,24 @@
+"""
+# jsii Calculator
+
+This library is used to demonstrate and test the features of JSII
+
+## Sphinx
+
+This file will be incorporated into the sphinx documentation.
+
+If this file starts with an "H1" line (in our case `# jsii Calculator`), this
+heading will be used as the Sphinx topic name. Otherwise, the name of the module
+(`jsii-calc`) will be used instead.
+
+## Code Samples
+
+```python
+# Example may have issues. See https://github.com/aws/jsii/issues/826
+# This is totes a magic comment in here, just you wait!
+foo = "bar"
+```
+"""
 import abc
 import datetime
 import enum