Doc improvements (#462)

* Explain about AWS::CDK::Metadata
* Explain about logical IDS versus physical names and add link
* Add "What Next?" section in the end with suggested next steps
* Other minor fixes.

Reference:
* Changed sidebar title from "Module Reference" to "Reference"
* Reduced TOC depth to 1

Misc:
* Changed Gitter URL
* Extract a `context` topic from `environments`.
* Refactored the versioning reporting section.

Fixes #451

packages/@aws-cdk/cdk/README.md

@@ -1,2 +1,5 @@
-## AWS Cloud Development Kit for Javascript
-This module is part of the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) project.
+## AWS Cloud Development Kit Core Library
+
+This library includes the basic building blocks of 
+the [AWS Cloud Development Kit](https://github.com/awslabs/aws-cdk) (AWS CDK).
+

packages/@aws-cdk/cdk/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aws-cdk/cdk",
   "version": "0.8.0",
-  "description": "AWS Cloud Development Kit for Javascript",
+  "description": "AWS Cloud Development Kit Core Library",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "jsii": {

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

@@ -43,5 +43,6 @@ as shared class libraries.
    logical-ids
    environments
    apps
+   context
    assets
    applets

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

@@ -0,0 +1,44 @@
+.. 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.
+
+.. _context:
+
+#####################
+Environmental Context
+#####################
+
+When you synthesize a stack to create a |CFN| template, the |cdk| might need information based on the
+environment (account and Region), such as the availability zones or AMIs available in the Region.
+To enable this feature, the |toolkit| uses *context providers*,
+and saves the context information into |cx-json|
+the first time you call |cx-synth-code|.
+
+The |cdk| currently supports the following context providers.
+
+:py:class:`AvailabilityZoneProvider <@aws-cdk/cdk.AvailabilityZoneProvider>`
+   Use this provider to get the list of all supported availability zones in this environment.
+   For example, the following code iterates over all of the AZs in the current environment.
+
+.. code:: js
+
+   // "this" refers to a parent Construct
+   const zones: string[] = new AvailabilityZoneProvider(this).availabilityZones;
+
+   for (let zone of zones) {
+      // do somethning for each zone!
+   }
+
+:py:class:`SSMParameterProvider <@aws-cdk/cdk.SSMParameterProvider>`
+   Use this provider to read values from the current Region's SSM parameter store.
+   For example, the follow code returns the value of the 'my-awesome-value' key:
+
+.. code:: js
+
+   const ami: string = new SSMParameterProvider(this).getString('my-awesome-value');

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

@@ -62,35 +62,3 @@ and explicitly specify accounts and Regions for production stacks.
    individual accounts so that you can deploy to multiple accounts using one
    invocation of ``cdk deploy``, but this feature is not available yet.
 
-.. _environment_context:
-
-Environmental Context
-=====================
-
-When you synthesize a stack to create a |CFN| template, the |cdk| might need information based on the
-environment (account and Region), such as the availability zones or AMIs available in the Region.
-To enable this feature, the |toolkit| uses *context providers*,
-and saves the context information into |cx-json|
-the first time you call |cx-synth-code|.
-
-The |cdk| currently supports the following context providers.
-
-:py:class:`@aws-cdk/cdk.AvailabilityZoneProvider`
-   Use this provider to get the list of all supported availability zones in this environment.
-   For example, the following code iterates over all of the AZs in the current environment.
-
-.. code:: js
-
-   const zones: string[] = new AvailabilityZoneProvider(this).availabilityZones;
-
-   for (let zone of zones) {
-      // do somethning for each zone!
-   }
-
-:py:class:`@aws-cdk/cdk.SSMParameterProvider`
-   Use this provider to read values from the current Region's SSM parameter store.
-   For example, the follow code returns the value of the 'my-awesome-value' key:
-
-.. code:: js
-
-   const ami: string = new SSMParameterProvider(this).getString('my-awesome-value');

packages/aws-cdk-docs/src/getting-started.rst

@@ -167,9 +167,7 @@ library includes the basic classes needed to write |cdk| stacks and apps.
                 <dependency>
                     <groupId>com.amazonaws.cdk</groupId>
                     <artifactId>aws-cdk</artifactId>
-
-                    <!-- make sure to use the CDK installed version here (i.e. "0.7.3-beta") -->
-                    <version>|cdk-version|</version>
+                    <version><!-- cdk-version --></version>
                 </dependency>
             </dependencies>
 
@@ -342,13 +340,12 @@ your project directory:
         Specify a 
         **CLASSPATH**, which contains both the compiled code and dependencies,
         to execute the Java program.
-        Use **maven-dependency-plugin** to produce the file **.classpath.txt**
+
+        Use **maven-dependency-plugin** in your **pom.xml** file to produce the file **.classpath.txt**
         whenever the project is compiled:
 
         .. code-block:: xml
 
-            <!-- pom.xml -->
-
             <build>
                 <plugins>
                     <!-- ... -->
@@ -388,7 +385,7 @@ your project directory:
             #!/bin/bash
             exec java -cp target/classes:$(cat .classpath.txt) com.acme.MyApp app $@
 
-        Define the :code:`-- app` option in **cdk.json**:
+        Define the :code:`--app` option in **cdk.json**:
 
         .. code-block:: json
 
@@ -523,9 +520,9 @@ together into a tree:
 * **parent** represents the parent construct. By specifying the parent construct
   upon initialization, constructs can obtain contextual information when they
   are initialized. For example, the region a stack is deployed to can be
-  obtained via a call to **Stack.find(this).requireRegion()**. See Context for
-  more information.
-* **id** is a local string that identifies the construct within the tree.
+  obtained via a call to :py:meth:`Stack.find(this).requireRegion() <@aws-cdk/cdk.Stack.requireRegion>`.
+  See :doc:`context` for more information.
+* **id** is a string that locally identifies this construct within the tree.
   Constructs must have a unique ID amongst their siblings.
 * **props** is the set of initialization properties for this construct.
 
@@ -563,7 +560,8 @@ stack:
             region: <your-default-region>
 
 Notice that your stack has been automatically associated with the default AWS
-account and region configured in the AWS CLI.
+account and region configured in the AWS CLI. See :doc:`environments` for more
+details on how to associate stacks to environments.
 
 .. _define_bucket:
 
@@ -593,8 +591,15 @@ Install the **@aws-cdk/aws-s3** package:
 
     .. group-tab:: Java
 
-        During beta, all |cdk| modules are bundles into the **aws-cdk** Maven package, so
-        there is no need to explicitly install the |S3| library.
+        Edit your **pom.xml** file:
+
+        .. code-block:: sh
+
+            <dependency>
+                <groupId>com.amazonaws.cdk</groupId>
+                <artifactId>aws-s3</artifactId>
+                <version><!-- cdk-version --></version>
+            </dependency>
 
 Next, define an |S3| bucket in the stack. |S3| buckets are represented by
 the :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` class:
@@ -667,11 +672,18 @@ the :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` class:
 
 A few things to notice:
 
-* **s3.Bucket** is construct. This means it's initialization signature has
-  **parent**, **id**, and **props**. In this case, the bucket is an immediate
-  child of **MyStack**, and its ID is 'MyFirstBucket'.
-* Since the bucket's :code:`versioned` property is :code:`true`,
-  versioning is enabled on the bucket.
+* :py:class:`Bucket <@aws-cdk/aws-s3.Bucket>` is a construct.
+  This means it's initialization signature has **parent**, **id**, and **props**.
+  In this case, the bucket is an immediate child of **MyStack**.
+* ``MyFirstBucket`` is the **logical id** of the bucket construct, **not** the physical name of the
+  S3 bucket. The logical ID is used to uniquely identify resources in your stack
+  across deployments. See :doc:`logical-ids` for more details on how to work
+  with logical IDs. To specify a physical name for your bucket, you can set the
+  :py:meth:`bucketName <@aws-cdk/aws-s3.BucketProps.bucketName>` property when
+  you define your bucket.
+* Since the bucket's :py:meth:`versioned <@aws-cdk/aws-s3.BucketProps.versioned>`
+  property is :code:`true`, `versioning <https://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html>`_
+  is enabled on the bucket.
 
 Compile your program:
 
@@ -698,8 +710,7 @@ Compile your program:
 Synthesize an |CFN| Template
 ============================
 
-Synthesize a 
-|cfn| template for the stack (don't forget to first compile the project if you have made any changes):
+Synthesize a |cfn| template for the stack:
 
 .. code-block:: sh
 
@@ -718,10 +729,21 @@ This command executes the |cdk| app and synthesize an |CFN| template for the
             Properties:
                 VersioningConfiguration:
                     Status: Enabled
+        CDKMetadata:
+            Type: 'AWS::CDK::Metadata'
+            Properties:
+                Modules: # ...
 
 You can see that the stack contains an **AWS::S3::Bucket** resource with the desired
 versioning configuration.
 
+.. note::
+
+    The **AWS::CDK::Metadata** resource was automatically added to your template
+    by the toolkit. This allows us to learn which libraries were used in your
+    stack. See :ref:`version-reporting` for more details and how to
+    :ref:`opt-out <version-reporting-opt-out>`.
+
 .. _deploy_stack:
 
 Deploying the Stack
@@ -731,7 +753,7 @@ Use **cdk deploy** to deploy the stack:
 
 .. code-block:: sh
 
-    cdk deploy hello-cdk
+    cdk deploy
 
 The **deploy** command synthesizes an |CFN| template from the stack
 and then invokes the |CFN| create/update API to deploy it into your AWS
@@ -806,7 +828,7 @@ the difference between the |cdk| app and the deployed stack:
 
 .. code-block:: sh
 
-    cdk diff hello-cdk
+    cdk diff
 
 The toolkit queries your AWS account for the current |CFN| template for the
 **hello-cdk** stack, and compares the result with the template synthesized from the app.
@@ -842,3 +864,13 @@ encryption for the bucket:
     [1/2] UPDATE_COMPLETE_CLEANUP_IN_PROGRESS  [AWS::CloudFormation::Stack] hello-cdk
     [2/2] UPDATE_COMPLETE     [AWS::CloudFormation::Stack] hello-cdk
     ✅  Deployment of stack hello-cdk completed successfully
+
+What Next?
+==========
+
+ * Learn more about :doc:`CDK Concepts <concepts>`
+ * Check out the `examples directory <https://github.com/awslabs/aws-cdk/tree/master/examples>`_ in your GitHub repository
+ * Learn about the rich APIs offered by the :doc:`AWS Construct Library <aws-construct-lib>`
+ * Work directly with CloudFormation using the :doc:`AWS CloudFormation Library <cloudformation>`
+ * Come talk to us on `Gitter <https://gitter.im/aws-cdk/Lobby?source=orgpage>`_
+

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

@@ -50,7 +50,7 @@ Additional Documentation and Resources
 In addition to this guide, the following are other resources available to |cdk| users:
 
 * `AWS Developer blog <https://aws.amazon.com/blogs/developer/>`_
-* `Gitter Channel <https://gitter.im/awslabs/aws-cdk>`_
+* `Gitter Channel <https://gitter.im/aws-cdk/lobby>`_
 * `Stack Overflow <https://stackoverflow.com/questions/tagged/aws-cdk>`_
 * `GitHub repository <https://github.com/awslabs/aws-cdk>`_
 
@@ -84,5 +84,5 @@ To obtain an AWS account, go to `aws.amazon.com <https://aws.amazon.com>`_ and c
    AWS CloudFormation Library <cloudformation>
    Examples <examples>
    Tools <tools>
-   Module Reference <reference>
+   Reference <reference>
 

packages/aws-cdk-docs/src/reference.rst.template

@@ -15,5 +15,5 @@ Reference
 #########
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 

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

@@ -19,7 +19,7 @@
 Command-line Toolkit (cdk)
 --------------------------
 
-``cdk`` (the |toolkit|) is the main tool you use to exercise your *CDK App*. It will execute
+``cdk`` (the |toolkit|) is the main tool you use to interact with your |*CDK App*|. It will execute
 the CDK app you have written and compiled, interrogate the application
 model you have defined, and produce and deploy the CloudFormation templates
 generated by it.
@@ -40,7 +40,6 @@ this option in a file called *cdk.json*:
       "app": "node bin/main.js"
    }
 
-
 Below are the actions you can take on your CDK app:
 
 .. code-block:: sh
@@ -86,7 +85,7 @@ Below are the actions you can take on your CDK app:
    If one of cdk.json or ~/.cdk.json exists, options specified there will be used
    as defaults. Settings in cdk.json take precedence.
 
-.. _versionReporting:
+.. _version-reporting:
 
 Version Reporting
 =================
@@ -108,6 +107,25 @@ The ``AWS::CDK::Metadata`` resource looks like the following:
      Properties:
        Modules: "@aws-cdk/core=0.7.2-beta,@aws-cdk/s3=0.7.2-beta,lodash=4.17.10"
 
-Opting out of version reporting can be done by adding the
-``--no-version-reporting`` argument to ``cdk`` command invocations or by setting
-the ``versionReporting`` key in ``./cdk.json`` or ``~/cdk.json`` to ``false``.
+.. _version-reporting-opt-out:
+
+Opting-out from Version Reporting
+
+
+To out-out, use one of the following methods:
+
+* Use the ``--no-version-reporting`` in ``cdk`` invocations:
+
+    .. code-block:: sh
+
+        cdk --no-version-reporting synth
+
+* Set ``versionReporting`` to ``false`` in **./cdk.json** or **~/cdk.json**:
+
+    .. code-block:: js
+
+        {
+          "app": "...",
+          "versionReporting": false
+        }
+