fix(pacmak): put package README into the right Python module

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

@@ -1030,8 +1030,11 @@ class Module implements PythonType {
     code.line('publication.publish()');
   }
 
+  /**
+   * Emit the README as module docstring if this is the entry point module (it loads the assembly)
+   */
   private emitModuleDocumentation(code: CodeMaker) {
-    if (this.package) {
+    if (this.package && this.loadAssembly) {
       code.line('"""');
       code.line(this.package.convertedReadme);
       code.line('"""');
@@ -1466,6 +1469,7 @@ class PythonGenerator extends Generator {
       assm,
     );
 
+    // This is the '<package>._jsii' module
     const assemblyModule = new Module(
       this.getAssemblyModuleName(assm),
       null,
@@ -1494,12 +1498,16 @@ class PythonGenerator extends Generator {
     // actually be generating a module, otherwise we'll generate a class within
     // that module.
     if (ns === this.assembly.name) {
+      // This is the main Python entry point (facade to the JSII module)
+
       const module = new Module(
         this.assembly.targets!.python!.module,
         ns,
         { assembly: this.assembly,
           assemblyFilename: this.getAssemblyFileName(),
-          loadAssembly: ns === this.assembly.name },
+          loadAssembly: ns === this.assembly.name,
+          package: this.package
+        },
       );
 
       this.package.addModule(module);

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

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

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

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

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

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

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

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

packages/jsii-pacmak/test/expected.jsii-calc/python/src/jsii_calc/__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

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

@@ -1,24 +1,3 @@
-"""
-# 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