docs: use npx projen commands in examples and clarify pdk vs projen (#…

…753)

To help clarify PDK vs Projen, use projen commands in examples instead of PDK cli, and reword parts
of the documentation. Also remove the migration banner from the README.

Fixes #678

README.md

@@ -1,5 +1,3 @@
-<a href="https://aws.github.io/aws-pdk/getting_started/migration_guide.html"><img src="docs/content/assets/images/rebrand_banner.png" width="1024px"></a>
-
 # Getting started
 
 ## What is the AWS PDK?

docs/content/faqs/index.md

@@ -1,5 +1,15 @@
 # Frequently Asked Questions
 
+## What's the difference between PDK and Projen?
+
+[Projen](https://projen.io/) is a framework which allows you to define and maintain complex project configuration through code. PDK uses this framework, and vends several Projen projects. PDK is not a replacement or alternative to Projen, but rather builds on Projen to define opinionated projects which work synergistically with one another.
+
+## What's the difference between PDK and CDK?
+
+[CDK](https://aws.amazon.com/cdk/) is a framework for defining AWS infrastructure as code. PDK vends several CDK constructs which can be used in traditional CDK projects, but are more powerful when used within the context of a PDK project. For example, the `StaticWebsite` CDK construct vended by PDK can be used in any CDK project to deploy the infrastructure to host a static website on AWS, however when the Infrastructure and CloudscapeReactTsWebsite PDK projects are used, the `StaticWebsite` CDK construct is automatically configured to deploy your Cloudscape website, and deploy the necessary runtime configuration to set up Cognito login for your website.
+
+While many of the PDK projects generate CDK code, PDK is not considered an abstraction over CDK. You still work with CDK to define your AWS infrastructure, but you may use these generated CDK constructs to supplement your CDK code.
+
 ## I want to change a “pre-defined” task (e.g.: add --verbose to a tsc compile task)
 
 Use the `reset` function:

docs/content/getting_started/index.md

@@ -7,7 +7,7 @@ This topic introduces you to important AWS PDK concepts and describes how to ins
 The AWS PDK lets you define your project structure as code in one of its supported programming languages. At its core, the AWS PDK is built on [Projen](https://github.com/projen/projen) and is a piece of software you should become familiar with if you want to become proficient with the PDK. In addition, alot of the constructs provided by the PDK generate CDK code which is used to deploy relevant infrastructure. The following expandable sections provide a quick primer on how these two key pieces of technology work.
 
 ??? "CDK Primer"
-    
+
     AWS Construct Development Kit (AWS CDK) allows you to model AWS infrastructure as code (IaC) in a variety of supported languages. By allowing you to define Infastructure programatically, you can create higher level abstractions which can be re-used in a variety of applications. The deployment mechanism used at AWS is Cloudformation and as such all CDK code 'synthesizes' into Cloudformation. You can think of this like code that compiles to some native format (i.e: Java -> ByteCode).
 
     To ground this in an example, let's create an S3 Bucket using the CDK:
@@ -143,7 +143,7 @@ The distributables for each language can be used directly as follows:
     ```
 
 !!!tip
-    Whilst the AWS PDK can be used directly via these package managers, we recommend bootstrapping via the `pdk new` command which negates the need to interact directly with these package managers. The package managers will still need to be installed however, refer to [prerequisites](index.md#prerequisites) for more information.
+    Whilst the AWS PDK can be used directly via these package managers, we recommend bootstrapping via the `npx projen new` command which negates the need to interact directly with these package managers. The package managers will still need to be installed however, refer to [prerequisites](index.md#prerequisites) for more information.
 
 ## Prerequisites
 
@@ -156,9 +156,11 @@ All AWS PDK developers, even those working in Python or Java, need Node.js 16 or
 !!!tip
     We recommend installing [`nvm`](https://github.com/nvm-sh/nvm#installing-and-updating) and configuring it to use Node 18.
 
-### PDK CLI
+### (Optional) PDK CLI
+
+The PDK CLI is a wrapper command which delegates to either a package manager or a projen command depending on the context. As a rule of thumb, this replaces the use of `npx projen` for commands shown in the documentation.
 
-Once your NodeJs runtime is set up, run the following command to install the pdk CLI:
+Once your NodeJS runtime is set up, run the following command to install the pdk CLI:
 
 ```bash
 npm install -g @aws/pdk
@@ -168,9 +170,6 @@ Run the following command to verify correct installation and print the version n
 
 `pdk --version`
 
-!!!warning
-    The `pdk` command is a wrapper command which delegates to either a package manager or a projen command depending on the context. As such it may be possible that certain arguments may not operate as expected.
-
 ### Git
 
 [Git](https://git-scm.com/) is also required to be installed and configured when bootstrapping new applications unless the `--no-git` flag is specified when executing the `pdk new` command.

docs/content/getting_started/shopping_list_app.md

@@ -189,11 +189,15 @@ The final step is the ensure our operations are exposed as part of the API by li
 
     use aws.protocols#restJson1
 
-    /// A sample smithy api
+    /// My Shopping List API
     @restJson1
     service MyApi {
         version: "1.0"
-        operations: [GetShoppingLists, PutShoppingList, DeleteShoppingList]
+        operations: [
+            GetShoppingLists
+            PutShoppingList
+            DeleteShoppingList
+        ]
         errors: [
             BadRequestError
             NotAuthorizedError
@@ -210,7 +214,7 @@ The final step is the ensure our operations are exposed as part of the API by li
 
 ### Build the API
 
-Now that we have our API defined, the final step is to build our code which will generate all of our type-safe bindings. To do so, run `pdk build` from the root of your PDK project.
+Now that we have our API defined, the final step is to build our code which will generate all of our type-safe bindings. To do so, run `npx projen build` from the root of your PDK project.
 
 Take some time now to inspect the code that was generated for you in the following locations:
 
@@ -335,7 +339,7 @@ Once you have saved your `.projenrc.ts` file, run `pdk` from the root to synthes
 
 ### Implement the handlers
 
-We now have everything we need to start implementing our handlers. 
+We now have everything we need to start implementing our handlers.
 
 Let's first by creating a shared file called `dynamo-client.ts` within the handlers `src` directory as follows:
 
@@ -564,7 +568,7 @@ Fantastic! We now have all of our API business logic implemented. Let's also upd
             expect(response.statusCode).toBe(200);
             expect((response.body as PutShoppingListResponseContent).shoppingListId).toBeDefined();
         });
-    });  
+    });
     ```
 
 === "delete-shopping-list.test.ts"
@@ -864,9 +868,9 @@ export class ApplicationStack extends Stack {
 We are now ready to deploy our API. To do so, run the following steps:
 
 ```bash
-pdk build
+npx projen build
 cd packages/infra
-pdk deploy:dev
+npx projen deploy:dev
 ```
 
 Once the deployment completes, we can test our API by navigating the the website (either via Cloudfront or locally) and trying out the API Explorer.
@@ -1334,7 +1338,7 @@ We can now test our UI locally by running the following command:
 
 ```bash
 cd packages/website
-pdk dev
+npx projen dev
 ```
 
 This will load a local server and open a browser showing your new application.
@@ -1348,9 +1352,9 @@ Have a play around with your website to ensure it is working as expected.
 If you are happy with your website locally, you can go ahead and deploy it to AWS Cloudfront by performing the following steps from the root directory:
 
 ```bash
-pdk build
+npx projen build
 cd packages/infra
-pdk deploy:dev
+npx projen deploy:dev
 ```
 
 Once the deployment completes, navigate to your cloudfront URL to play around with your deployed website.