update formatting of cdk docs (#218)

* update formatting of cdk docs

* add missing period

.vscode/settings.json

@@ -31,6 +31,8 @@
         "forcerm",
         "kwarg",
         "lambci",
+        "mycdkmodule",
+        "myothercdkmodule",
         "nondockerizepip",
         "rxref",
         "stubbers"

docs/source/cdk/advanced_features.rst

@@ -0,0 +1,46 @@
+#################
+Advanced Features
+#################
+
+Advanced features and detailed information for using CDK with Runway.
+
+
+***********
+Build Steps
+***********
+
+Build steps (e.g. for compiling TypeScript) can be specified in the module options.
+These steps will be run before each diff, deploy, or destroy.
+
+.. rubric:: Example
+.. code-block:: yaml
+
+  ---
+  deployments:
+    - modules:
+        - path: mycdkmodule.cdk
+          environments:
+            dev: true
+          options:
+            build_steps:
+              - npx tsc
+
+
+****************
+Disabling NPM CI
+****************
+
+At the start of each module execution, Runway will execute ``npm ci`` to ensure
+the CDK is installed in the project (so Runway can execute it via
+``npx cdk``. This can be disabled (e.g. for use when the ``node_modules``
+directory is pre-compiled) via the ``skip_npm_ci`` module option:
+
+.. rubric:: Example
+.. code-block:: yaml
+
+  ---
+  deployments:
+    - modules:
+        - path: mycdkmodule.cdk
+          options:
+            skip_npm_ci: true

docs/source/cdk/configuration.rst

@@ -0,0 +1,51 @@
+#############
+Configuration
+#############
+
+Standard `CDK <https://docs.aws.amazon.com/cdk/latest/guide/getting_started.html>`__ rules apply but, we have some added prerequisites, recommendations, and caveats.
+
+
+*************
+Prerequisites
+*************
+
+- `npm installed on the system <https://www.npmjs.com/get-npm>`__
+- CDK must be a dev dependency of the module (e.g. ``npm install --save-dev aws-cdk``)
+
+We strongly recommend you commit the package-lock.json that is generated after running ``npm install``.
+
+
+************
+Environments
+************
+
+Unlike some other module types, CDK does not have file that can be used to configure an environment.
+It can only be configured using the ``environments`` option of a deployment and/or module (see :ref:`Runway Config File <runway-config>` for details).
+
+
+Runway Config
+=============
+
+.. rubric:: Top-level
+.. code-block:: yaml
+
+  ---
+  deployments:
+    - modules:
+        - path: mycdkmodule.cdl
+          environments:
+            dev: true
+            prod: true
+    - modules:
+        - path: myothercdkmodule.cdk
+      environments:
+        dev: true
+        prod: true
+
+.. rubric:: In Module Directory
+.. code-block:: yaml
+
+  ---
+  environments:
+    dev: true
+    prod: true

docs/source/cdk/directory_structure.rst

@@ -0,0 +1,61 @@
+###################
+Directory Structure
+###################
+
+Example directory structures for a CDK module.
+
+
+**********
+C# Example
+**********
+
+.. code-block::
+
+  .
+  ├── add-project.hook.d.ts
+  ├── cdk.json
+  ├── package.json
+  ├── package-lock.json
+  └── src
+      ├── HelloCdk
+      │   ├── HelloCdk.csproj
+      │   ├── HelloConstruct.cs
+      │   ├── HelloStack.cs
+      │   └── Program.cs
+      └── HelloCdk.sln
+
+
+**************
+Python Example
+**************
+
+.. code-block::
+
+  .
+  ├── Pipfile
+  ├── Pipfile.lock
+  ├── app.py
+  ├── cdk.json
+  ├── hello
+  │   ├── __init__.py
+  │   ├── hello_construct.py
+  │   └── hello_stack.py
+  ├── package.json
+  └── package-lock.json
+
+
+******************
+TypeScript Example
+******************
+
+.. code-block::
+
+  .
+  ├── bin
+  │   └── sample.ts
+  ├── cdk.json
+  ├── lib
+  │   └── sample-stack.ts
+  ├── package.json
+  ├── package.json
+  └── tsconfig.json

docs/source/index.rst

@@ -37,6 +37,30 @@ Very simple configuration to:
 Module Configuration
 ********************
 
+
+.. _mod-cdk:
+
+AWS Cloud Development Kit (CDK)
+===============================
+
+The CDK module type is deployed using the `AWS Cloud Development Kit (CDK) <https://docs.aws.amazon.com/cdk/latest/guide/home.html>`__.
+Runway uses `system installed npm <https://www.npmjs.com/get-npm>`__ to install the CDK per-module.
+This means that the CDK must be included as a dev dependency in the **package.json** of the module.
+
+- `Configuration <cdk/configuration.html>`__
+- `Directory Structure <cdk/directory_structure.html>`__
+- `Advanced Features <cdk/advanced_features.html>`__
+
+.. toctree::
+   :caption: AWS Cloud Development Kit (CDK)
+   :maxdepth: 2
+   :hidden:
+
+   cdk/configuration
+   cdk/directory_structure
+   cdk/advanced_features
+
+
 CloudFormation & Troposphere
 ============================
 

docs/source/module_configuration/index.rst

@@ -7,7 +7,6 @@ Module Configurations
     :maxdepth: 1
     :name: mod-configs
 
-    cdk
     custom
     kubernetes
     serverless