chore: add api-docs auto generation (#232)

This PR introduces a new tool [typedoc](https://typedoc.org/) which
automatically generates API docs from TypeScript code. I think this is
easier than having to remember to manually update the API documentation.
It also forces us to add code comments to document the API.

I've also added a couple of scripts to the `build` script to ensure we
run `docs`, `format`, && `lint` as part of `build`.

README.md

@@ -146,150 +146,19 @@ create the following staging resources.
 5. [aws.s3.BucketPolicy](https://www.pulumi.com/registry/packages/aws/api-docs/s3/bucketpolicy/)
   - Require SSL
 
-## API
-
-### `App`
-
-A Pulumi CDK App component. This is the entrypoint to your Pulumi CDK application.
-In order to deploy a CDK application with Pulumi, you must start with this class.
-
-#### `constructor`
-
-Create and register an AWS CDK app deployed with Pulumi.
-
-```ts
-constructor(id: string, createFunc: (scope: App) => void | AppOutputs, props?: AppResourceOptions)
-```
-
-Parameters:
-* `id`: The _unique_ name of the app
-* `createFunc`: A callback function where all CDK Stacks must be created
-* `options`: A bag of options that control the resource's behavior
-
-#### `outputs`
-
-The collection of outputs from the Pulumi CDK App represented as Pulumi Outputs.
-Each `CfnOutput` defined in each AWS CDK Stack will populate a value in the
-outputs.
-
-```ts
-outputs: { [outputId: string]: pulumi.Output<any> }
-```
-
-#### `AppResourceOptions`
-
-Options specific to the App Component
-
-```ts
-interface AppResourceOptions
-```
-
-#### `remapCloudControlResource`
-
-This optional method can be implemented to define a mapping to override and/or
-provide an implementation for a CloudFormation resource type that is not (yet)
-implemented in the AWS Cloud Control API (and thus not yet available in the
-Pulumi AWS Native provider). Pulumi code can override this method to provide a
-custom mapping of CloudFormation elements and their properties into Pulumi
-CustomResources, commonly by using the AWS Classic provider to implement the
-missing resource.
-
-```ts
-remapCloudControlResource(logicalId: string, typeName: string, props: any, options: pulumi.ResourceOptions): ResourceMapping | undefined;
-```
-
-Parameters:
-* `logicalId`: The logical ID of the resource being mapped.
-* `typeName`: The CloudFormation type name of the resource being mapped.
-* `props`: The bag of input properties to the CloudFormation resource being mapped.
-* `options`: The set of Pulumi ResourceOptions to apply to the resource being mapped.
-
-Returns an object containing one or more logical IDs mapped to Pulumi resources
-that must be created to implement the mapped CloudFormation resource, or else
-undefined if no mapping is implemented.
-
-#### `appId`
-
-This is a unique identifier for the application. It will be used in the names of the
-staging resources created for the application. This `appId` should be unique across apps.
-
-### `Stack`
-
-A Construct that represents an AWS CDK stack deployed with Pulumi. In order to
-deploy a CDK stack with Pulumi, it must derive from this class.
-
-#### `constructor`
-
-Create and register an AWS CDK stack deployed with Pulumi.
-
-```ts
-constructor(app: App, name: string, options?: StackOptions)
-```
-
-Parameters:
-* `app`: The Pulumi CDK App
-* `name`: The _unique_ name of the resource.
-* `options`: A bag of options that control this resource's behavior.
-
-
-#### `asOutput`
-
-Convert a CDK value to a Pulumi output.
-
-Parameters:
-* `v`: A CDK value.
-
-```ts
-asOutput<T>(v: T): pulumi.Output<T>
-```
-
-### `StackOptions`
-
-Options specific to the Stack component.
-
-```ts
-interface StackOptions
-```
-
-
-### `asString`
-
-Convert a Pulumi Output to a CDK string value.
+### ECR Resources
 
-```ts
-function asString<T>(o: pulumi.Output<T>): string
-```
-
-Parameters:
- * `o`: A Pulumi Output value which represents a string.
-
-Returns A CDK token representing a string value.
-
-### `asNumber`
-
-Convert a Pulumi Output to a CDK number value.
-
-```ts
-function asNumber<T>(o: pulumi.Output<T>): number
-```
-
-Parameters:
- * `o`: A Pulumi Output value which represents a number.
-
-Returns A CDK token representing a number value.
-
-### `asList`
-
-Convert a Pulumi Output to a list of CDK values.
+When any image assets are added to your application, CDK will automatically
+create the following staging resources.
 
-```ts
-function asList<T>(o: pulumi.Output<T>): string[]
-```
+1. `aws.ecr.Repository`
+  - `imageTagMutability`: `IMMUTABLE`
+2. `aws.ecr.LifecyclePolicy`
+  - Expire old images when the number of images > 3
 
-Parameters:
- * `o`: A Pulumi Output value which represents a list.
+## API
 
-Returns a CDK token representing a list of values.
+See [API Docs](./api-docs/README.md) for more details.
 
 ## Building locally
 
@@ -298,7 +167,7 @@ Install dependencies, build library, and link for local usage.
 ```sh
 $ yarn install
 $ yarn build
-$ pushd lib && yarn link && popd
+$ yarn link
 ```
 
 Run unit test:

api-docs/Namespace.interop.md

@@ -0,0 +1,89 @@
+[**@pulumi/cdk**](README.md) • **Docs**
+
+***
+
+[@pulumi/cdk](README.md) / interop
+
+# interop
+
+## Type Aliases
+
+### ResourceAttributeMapping
+
+> **ResourceAttributeMapping**: `object`
+
+Use this type if you need to control the attributes that are available on the
+mapped resource. For example if the CFN resource has an attribute called `resourceArn` and
+the mapped resource only has an attribute called `arn` you can return the extra `resourceArn`
+attribute
+
+#### Type declaration
+
+| Name | Type | Defined in |
+| ------ | ------ | ------ |
+| `attributes`? | `object` | [interop.ts:88](https://github.com/pulumi/pulumi-cdk/blob/890dc36200787bf0cc83014ee6ebc4bc46e0db99/src/interop.ts#L88) |
+| `resource` | `pulumi.Resource` | [interop.ts:87](https://github.com/pulumi/pulumi-cdk/blob/890dc36200787bf0cc83014ee6ebc4bc46e0db99/src/interop.ts#L87) |
+
+#### Example
+
+```ts
+return {
+  resource: mappedResource,
+  attributes: {
+    resourceArn: mappedResource.arn,
+  }
+}
+```
+
+#### Defined in
+
+[interop.ts:86](https://github.com/pulumi/pulumi-cdk/blob/890dc36200787bf0cc83014ee6ebc4bc46e0db99/src/interop.ts#L86)
+
+***
+
+### ResourceAttributeMappingArray
+
+> **ResourceAttributeMappingArray**: [`ResourceAttributeMapping`](Namespace.interop.md#resourceattributemapping) & `object`[]
+
+Use this type if a single CFN resource maps to multiple AWS resources
+
+#### Defined in
+
+[interop.ts:94](https://github.com/pulumi/pulumi-cdk/blob/890dc36200787bf0cc83014ee6ebc4bc46e0db99/src/interop.ts#L94)
+
+***
+
+### ResourceMapping
+
+> **ResourceMapping**: [`ResourceAttributeMapping`](Namespace.interop.md#resourceattributemapping) \| `pulumi.Resource` \| [`ResourceAttributeMappingArray`](Namespace.interop.md#resourceattributemappingarray)
+
+#### Defined in
+
+[interop.ts:96](https://github.com/pulumi/pulumi-cdk/blob/890dc36200787bf0cc83014ee6ebc4bc46e0db99/src/interop.ts#L96)
+
+## Functions
+
+### normalize()
+
+> **normalize**(`value`, `cfnType`?, `pulumiProvider`?): `any`
+
+normalize will take the resource properties for a specific CloudFormation resource and
+will covert those properties to be compatible with Pulumi properties.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `value` | `any` | The resource properties to be normalized |
+| `cfnType`? | `string` | The CloudFormation resource type being normalized (e.g. AWS::S3::Bucket). If no value is provided then property conversion will be done without schema knowledge |
+| `pulumiProvider`? | `PulumiProvider` | The pulumi provider to read the schema from. If `cfnType` is provided then this defaults to PulumiProvider.AWS_NATIVE |
+
+#### Returns
+
+`any`
+
+The normalized resource properties
+
+#### Defined in
+
+[interop.ts:41](https://github.com/pulumi/pulumi-cdk/blob/890dc36200787bf0cc83014ee6ebc4bc46e0db99/src/interop.ts#L41)