Documentation updates

packages/aws-cdk-docs/src/applets.rst

@@ -0,0 +1,76 @@
+.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+   This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
+   International License (the "License"). You may not use this file except in compliance with the
+   License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
+
+   This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+   either express or implied. See the License for the specific language governing permissions and
+   limitations under the License.
+
+.. _applets:
+
+#######
+Applets
+#######
+
+.. note:: Currently the |cdk| only supports applets published as JavaScript modules.
+
+Applets are files in the YAML or JSON format that have the following root attribute,
+where MODULE can represent
+a local file, such as :code:`./my-module`,
+a local dependency, such as :code:`my-dependency`,
+or a global module, such as :code:`@aws-cdk/s3`
+and CLASS is the name of a class exported by the module.
+
+.. code:: js
+
+   applet: MODULE[:CLASS]
+
+If CLASS is not specified, :code:`Applet` is used as the default class name.
+Therefore, you need only refer to |cdk| construct libraries that export
+an :code:`Applet` class by their library name.
+
+The rest of the YAML file is applet-dependent.
+The object is passed as :code:`props` when the applet object is instantiated
+and added to an |cdk| app created by **cdk-applet-js**.
+
+Use **cdk-applet-js** *applet* to run the applet, create an |cdk| app,
+and use that with the |cdk| tools, as shown in the following example.
+
+.. code-block:: sh
+
+   cdk --app "cdk-applet-js ./my-applet.yaml" synth
+
+To make the applet file executable and use the host as a shebang
+on Unix-based systems, such as Linux, MacOS, or Windows Bash shell,
+create a script similar to the following.
+
+.. code-block:: sh
+
+   #!/usr/bin/env cdk-applet-js
+
+   applet: aws-cdk-codebuild
+   source: arn:aws:codecommit:::my-repository
+   image: node:8.9.4
+   compute: large
+   build:
+      - npm install --unsafe-perm
+      - npm test
+      - npm pack --unsafe-perm
+
+To execute the applet and synthesize an |CFN| template,
+use the following command.
+
+.. code-block:: sh
+
+   cdk synth --app "./build.yaml"
+
+To avoid needing **--app** for every invocation,
+add the following entry to *cdk.json*.
+
+.. code-block:: json
+
+   {
+      "app": "./build.yaml"
+   }

packages/aws-cdk-docs/src/apps.rst

@@ -0,0 +1,84 @@
+.. Copyright 2010-2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+   This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0
+   International License (the "License"). You may not use this file except in compliance with the
+   License. A copy of the License is located at http://creativecommons.org/licenses/by-nc-sa/4.0/.
+
+   This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+   either express or implied. See the License for the specific language governing permissions and
+   limitations under the License.
+
+.. _apps:
+
+####
+Apps
+####
+
+The main artifact of an |cdk| program is called a *CDK App*.
+This is an executable program that can be used to synthesize deployment artifacts
+that can be deployed by supporting tools like the |toolkit|,
+which are described in :doc:`tools`.
+
+Tools interact with apps through the program's **argv**/**stdout** interface,
+which can be easily implemented using the **App** class,
+as shown in the following example.
+
+.. code-block:: js
+
+   import { App } from '@aws-cdk/core'
+
+   const app = new App(process.argv); // input: ARGV
+
+   // <add stacks here>
+
+   process.stdout.write(app.run());
+
+An |app-construct| is a collection of |stack| objects, as shown in the following
+example.
+
+.. code-block:: js
+
+   import { App } from '@aws-cdk/core'
+   import { MyStack } from './my-stack'
+
+   const app = new App(process.argv);
+
+   const dev = new MyStack(app, { name: 'Dev', region: 'us-west-2', dev: true })
+   const preProd = new MyStack(app, { name: 'PreProd', region: 'us-west-2', preProd: true })
+   const prod = [
+       new MyStack(app, { name: 'NAEast', region: 'us-east-1' }),
+       new MyStack(app, { name: 'NAWest', region: 'us-west-2' }),
+       new MyStack(app, { name: 'EU', region: 'eu-west-1', encryptedStorage: true })
+   ]
+
+   new DeploymentPipeline(app, {
+       region: 'us-east-1',
+       strategy: DeploymentStrategy.Waved,
+       preProdStages: [ preProd ],
+       prodStages: prod
+   });
+
+   process.stdout.write(app.run());
+
+Use the |toolkit| to list the stacks in this executable,
+as shown in the following example.
+
+.. code-block:: sh
+
+   cdk list
+   [
+      { name: "Dev", region: "us-west-2" }
+      { name: "PreProd", region: "us-west-2" },
+      { name: "NAEast", region: "us-east-1" },
+      { name: "NAWest", region: "us-west-2" },
+      { name: "EU", region: "eu-west-1" },
+      { name: "DeploymentPipeline", region: 'us-east-1' }
+   ]
+
+Or deploy one of the stacks,
+as shown in the following example.
+
+.. code-block:: sh
+
+   cdk deploy Dev
+   ...

packages/aws-cdk-docs/src/cloudformation.rst

@@ -21,18 +21,14 @@ This section includes information about |cdk| features that most developers do n
 Creating |l1| Constructs
 ========================
 
-|l1| constructs are found in the :py:mod:`aws-cdk-resources` package. They map directly onto |cfn|
+|l1| constructs are found in the :py:mod:`@aws-cdk/resources` package. They map directly onto |cfn|
 resources.
 
 .. important::
 
   In general, you shouldn't need to use this type of Constructs, unless you have
   special requirements or there is no Construct Library for the AWS resource you
-  need yet. You should use other packages with higher-level constructs instead. See
-  :ref:`l1_vs_l2` for a comparison between the construct types.
-
-The remainder of this section is for those who need to create a stack using a |l1| construct,
-or want to create a |l2| construct from |l1| constructs.
+  need yet. You should use other packages with higher-level constructs instead.
 
 .. _construct_attributes: