chore(python): documentation improvements (#2028)

Improved the documentability of generated Python code by reducing the
use of forward references through keeping track of types that were
already emitted; and by emitting the kind of forward reference that `sphinx`'
`autodoc` extension is able to resolve (forward references within a sub-package
must be relative to that sub-package; and nested declarations can not
use their surrounding type's name in forward references (those must be relative
to the surrounding type's context).

Additionally, removed duplicated headings that were generated for
documentation segments (`see`, `returns`, ...), as those were causing
redundant content to appear on the generated docsite.

This completely removes `ForwardRef` instances from the Python
reference documentation (as was checked by issuing a recursive
`grep` on the generated documentation).

Fixes #474
Related #1919 

---

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/compliance.ts

@@ -2820,3 +2820,23 @@ export class DynamicPropertyBearerChild extends DynamicPropertyBearer {
     return oldValue;
   }
 }
+
+/**
+ * Validates that nested classes get correct code generation for the occasional
+ * forward reference.
+ */
+export class LevelOne {
+  public constructor(public readonly props: LevelOneProps) {}
+}
+export interface LevelOneProps {
+  readonly prop: LevelOne.PropProperty;
+}
+export namespace LevelOne {
+  export interface PropProperty {
+    readonly prop: PropBooleanValue;
+  }
+
+  export interface PropBooleanValue {
+    readonly value: boolean;
+  }
+}

packages/jsii-calc/test/assembly.jsii

@@ -8169,6 +8169,148 @@
       ],
       "name": "JsonFormatter"
     },
+    "jsii-calc.LevelOne": {
+      "assembly": "jsii-calc",
+      "docs": {
+        "stability": "stable",
+        "summary": "Validates that nested classes get correct code generation for the occasional forward reference."
+      },
+      "fqn": "jsii-calc.LevelOne",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "locationInModule": {
+          "filename": "lib/compliance.ts",
+          "line": 2829
+        },
+        "parameters": [
+          {
+            "name": "props",
+            "type": {
+              "fqn": "jsii-calc.LevelOneProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 2828
+      },
+      "name": "LevelOne",
+      "properties": [
+        {
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 2829
+          },
+          "name": "props",
+          "type": {
+            "fqn": "jsii-calc.LevelOneProps"
+          }
+        }
+      ]
+    },
+    "jsii-calc.LevelOne.PropBooleanValue": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.LevelOne.PropBooleanValue",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 2839
+      },
+      "name": "PropBooleanValue",
+      "namespace": "LevelOne",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 2840
+          },
+          "name": "value",
+          "type": {
+            "primitive": "boolean"
+          }
+        }
+      ]
+    },
+    "jsii-calc.LevelOne.PropProperty": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.LevelOne.PropProperty",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 2835
+      },
+      "name": "PropProperty",
+      "namespace": "LevelOne",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 2836
+          },
+          "name": "prop",
+          "type": {
+            "fqn": "jsii-calc.LevelOne.PropBooleanValue"
+          }
+        }
+      ]
+    },
+    "jsii-calc.LevelOneProps": {
+      "assembly": "jsii-calc",
+      "datatype": true,
+      "docs": {
+        "stability": "stable"
+      },
+      "fqn": "jsii-calc.LevelOneProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "lib/compliance.ts",
+        "line": 2831
+      },
+      "name": "LevelOneProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable"
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "lib/compliance.ts",
+            "line": 2832
+          },
+          "name": "prop",
+          "type": {
+            "fqn": "jsii-calc.LevelOne.PropProperty"
+          }
+        }
+      ]
+    },
     "jsii-calc.LoadBalancedFargateServiceProps": {
       "assembly": "jsii-calc",
       "datatype": true,
@@ -13970,5 +14112,5 @@
     }
   },
   "version": "0.0.0",
-  "fingerprint": "Ddy05wOucU4yV7YP5fPUzEjiOsl5AGPrwJS7pXpJRPI="
+  "fingerprint": "ary2D/3pPPIqMW0FmZnYMsKzvk8r29qmK5+1KyEcTQA="
 }