chore(docs): Project Setup

.github/workflows/docker.yml

@@ -6,6 +6,7 @@ on:
     paths-ignore:
       - "**.md"
       - "docs/**"
+      - "website/**"
 
 jobs:
   build-docker-image:

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Docs
+on:
+  - pull_request
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Get yarn cache directory path
+        id: yarn-cache-dir-path
+        run: echo "::set-output name=dir::$(yarn cache dir)"
+      - uses: actions/cache@v2
+        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
+        with:
+          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+      - name: installing dependencies
+        run: |
+          yarn install
+      - name: prettier
+        run: |
+          yarn prettier --check ./website

.github/workflows/examples.yml

@@ -4,6 +4,7 @@ on:
     paths-ignore:
       - "**.md"
       - "docs/**"
+      - "website/**"
 
 jobs:
   build-example-matrix:

.github/workflows/integration.yml

@@ -4,6 +4,7 @@ on:
     paths-ignore:
       - "**.md"
       - "docs/**"
+      - "website/**"
 
 jobs:
   prepare-integration-tests:

website/docs-template.html.md

@@ -7,4 +7,4 @@ description: "TODO: describe me"
 
 # Example
 
-Lorem Ipsum and so on
+Lorem Ipsum and so on

website/docs/cdktf/cli-reference/commands.html.md

@@ -20,7 +20,6 @@ The CDK for Terraform CLI has the following commands:
 - [synth](/docs/cdktf/cli-reference/commands.html#synth)
 - [watch](/docs/cdktf/cli-reference/commands.html#watch)
 
-
 ## completion
 
 This command outputs a script that you can use to set up autocompletion for bash or zsh.
@@ -102,16 +101,17 @@ Options:
 **Examples**
 
 Convert a local file.
-``` bash
+
+```bash
 cat main.tf | cdktf convert > imported.ts`
 ```
 
 Convert HCL in your clipboard to Python on OSX.
-``` bash
+
+```bash
 pbpaste | cdktf convert --language python | pbcopy
 ```
 
-
 ## deploy
 
 This command deploys a given application.
@@ -223,6 +223,7 @@ $ cdktf diff
 ```
 
 ## get
+
 This command downloads the providers and modules for an application and
 generates CDK constructs for them. It can use the `cdktf.json` configuration file to read the list of providers and modules.
 
@@ -319,6 +320,7 @@ Create a new Typescript project from an existing Terraform codebase. Currently,
 ```bash
 $ cdktf init --template="typescript" --from-terraform-project /path/to/terraform/project
 ```
+
 ## login
 
 This command helps log in to Terraform Cloud by fetching a Terraform Cloud API token.
@@ -402,7 +404,6 @@ The `watch` command watches a directory for changes and automatically synthesize
 
 Watch reads your root `.gitignore` file to determine which files trigger a `synth` and it uses the `outdir` of your `cdktf.json` (or the default `cdktf.out`) to do so for a deploy. It will generate a checksum of the subdirectory containing the Terraform code for your stack to skip deploys if the synthesized Terraform config did not change.
 
-
 ### Prerequisites
 
 Before using `watch` you should:
@@ -425,4 +426,4 @@ cdktf watch --stack dev --auto-approve
 
 Set the `CDKTF_LOG_LEVEL` environment variable to `all` and set `CDKTF_DISABLE_LOGGING` to `false`.
 
-The debug output is directed to a `cdktf.log` file in your projects root directory. The log contains information about detected file system changes and the actions they triggered.
+The debug output is directed to a `cdktf.log` file in your projects root directory. The log contains information about detected file system changes and the actions they triggered.

website/docs/cdktf/cli-reference/configuration.html.md

@@ -60,10 +60,8 @@ Options can be specified via environment variables with the "CDKTF_" prefix (e.g
 
 If running in automated environments, the dynamic CLI output rendering can be forced to be static with the `CI` environment variable set to a true value.
 
-
 ## Configuration
 
 You can configure the behavior of the Terraform CDK CLI by adding a `cdktf.json` file in your project root directory.
 
 TODO: Add link to cdktf.json page
-

website/docs/cdktf/concepts/architecture.html.md

@@ -14,5 +14,3 @@ When you use CDKTF, you create an **application** that uses CDKTF libraries to c
 ## Applications
 
 CDK for Terraform apps are structured as a tree of [constructs](https://github.com/aws/constructs). The classes `App`, `TerraformStack`, `TerraformResource` and `Resource` are all deriving from `Construct` and are therefore represented as a node in the application tree, where the `App` node is the root.
-
-

website/docs/cdktf/concepts/fundamentals/assets.html.md

@@ -52,4 +52,4 @@ class MyStack extends TerraformStack {
 const app = new App();
 new MyStack(app, "demo");
 app.synth();
-```
+```

website/docs/cdktf/concepts/fundamentals/cdktf-json.md

@@ -0,0 +1,174 @@
+---
+layout: "docs"
+page_title: "Configuration"
+sidebar_current: "cdktf"
+description: "Learn how to build a CDKTF application from a template, project structure, and configuration. "
+---
+
+# Configuration
+
+The `cdktf.json` file lets you configure the behavior of the CDK for Terraform CLI and define the [providers](/docs/cdktf/concepts/fundamentals/providers.html) and [modules](docs/cdktf/concepts/fundamentals/modules.html) you want to use. Installing CDK for Terraform with a [built-in template](/docs/cdktf/create-and-deploy/project-setup.html) generates a basic `cdktf.json` file in your root directory that you can customize for your application.
+
+## Specification
+
+```ts
+export enum Language {
+  TYPESCRIPT = "typescript",
+  PYTHON = "python",
+  CSHARP = "csharp",
+  JAVA = "java",
+  GO = "go",
+}
+
+export interface TerraformDependencyConstraint {
+  readonly name: string; // name of the module / provider
+  readonly source?: string; // path / url / registry identifier for the module / provider
+  readonly version?: string; // version constraint (https://www.terraform.io/docs/language/providers/requirements.html#version-constraints)
+}
+type RequirementDefinition = string | TerraformDependencyConstraint;
+
+export interface Config {
+  readonly app?: string; // The command to run in order to synthesize the code to Terraform compatible JSON
+  readonly language?: Language; // Target language for building provider or module bindings. Currently supported: `typescript`, `python`, `java`, `csharp`, and `go`
+  readonly output: string; // Default: 'cdktf.out'. Where the synthesized JSON should go. Also will be the working directory for Terraform operations
+  readonly codeMakerOutput: string; // Default: '.gen'. Path where generated provider bindings will be rendered to.
+  readonly projectId: string; // Default: generated UUID. Unique identifier for the project used to differentiate projects
+  readonly terraformProviders?: RequirementDefinition[]; // Terraform Providers to build
+  readonly terraformModules?: RequirementDefinition[]; // Terraform Modules to build
+}
+```
+
+## Minimal Configuration
+
+The most basic configuration only defines `app`. This is useful when you plan to use [prebuilt providers](/docs/cdktf/concepts/fundamentals/providers.html) and you don't need to generate any provider or module bindings.
+
+```json
+{
+  "app": "npm run --silent compile && node main.js"
+}
+```
+
+## Declare Providers and Modules
+
+While we have a selection of pre-built providers (link), there are cases where you want to generate the type bindings for providers yourself (e.g. when a provider is not present as pre built provider, or a specific provider version is required for some reason). Modules always have to be built via `cdktf get` and thefore have to be present in the `cdktf.json`.
+
+You must declare all of the providers and modules you want to generate code bindings for in your `cdktf.json` file. The [schema](https://www.terraform.io/docs/language/providers/requirements.html#source-addresses) for both providers and modules in CDK for Terraform consists of a name, a [source](https://www.terraform.io/docs/language/providers/requirements.html#source-addresses), and a [version constraint](https://www.terraform.io/docs/language/providers/requirements.html#version-constraints).
+
+You can declare providers and modules using either JSON or a string with the format `source@ ~> version` .
+
+### Provider Source
+
+- **HashiCorp providers**: You can specify official HashiCorp [maintained providers](https://registry.terraform.io/browse/providers?tier=official) by their name on the Terraform Registry. For example, you can use `aws` to declare the official [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest): `aws@ ~> 2.0`
+
+- **Community providers**: You must provide the fully-qualified name. The fully-qualified name is available on the provider's registry page. For example, to define the [DataDog provider](https://registry.terraform.io/providers/DataDog/datadog/latest): `DataDog/datadog@ ~> 3.4.0`
+
+### Module Source
+
+- For modules on the Terraform Registry, provide the the full registry namespace. For example, to define the [AWS VPC module](https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/latest): `terraform-aws-modules/vpc/aws@ ~> 3.2.0`.
+
+- For local modules please use the object format:
+  TODO Please explain why.
+
+  ```jsonc
+  {
+    // ...
+    "moduleRequirements": [
+      {
+        "name": "myLocalModule",
+        "source": "../my-modules/local-module"
+      }
+    ]
+  }
+  ```
+
+### Version Constraint
+
+When you declare providers and modules in the string format, add the [version constraint](https://www.terraform.io/docs/language/expressions/version-constraints.html#version-constraint-syntax) after the provider or module name separated by an `@`. For example, so `provider|module@ ~> version`. You can also omit the version constraint if you do not want to specify a particular version. When you omit the version constraint, CDK for Terraform downloads and uses the latest version.
+
+When you declare providers in JSON, add the constraint in the `version` property. TODO Please provide an example of this in object format.
+
+## Examples
+
+### Changing the Output Directory
+
+Defining `output` changes the directory where `cdktf` will put your generated Terraform configuration file. All Terraform operations will be performed from this directory.
+
+The example below synthesizes the JSON Terraform configuration into `my-workdir`:
+
+```json
+{
+  "app": "npm run --silent compile && node main.js",
+  "output": "my-workdir"
+}
+```
+
+### Building Providers
+
+With this `terraformProviders` configuration, a `cdktf get` will build the latest AWS provider within the 2.X version range. The generated code will be saved into `.gen` by default. This can be adjusted with `codeMakerOutput`, see other examples below.
+
+```json
+{
+  "language": "typescript",
+  "app": "npm run --silent compile && node main.js",
+  "terraformProviders": ["aws@~> 2.0"]
+}
+```
+
+### Building Modules
+
+With this `terraformModules` configuration, a `cdktf get` will build the latest `terraform-aws-modules/vpc/aws` module from the Terraform Registry. The generated code will be saved into `.gen` by default. This can be adjusted with `codeMakerOutput` - see other examples below.
+
+```json
+{
+  "language": "typescript",
+  "app": "npm run --silent compile && node main.js",
+  "terraformModules": ["terraform-aws-modules/vpc/aws"]
+}
+```
+
+### Building Providers & Modules
+
+This combines examples above. A `cdktf get` will build both the AWS provider and the latest `terraform-aws-modules/vpc/aws` module from the Terraform Registry.
+
+```json
+{
+  "language": "typescript",
+  "app": "npm run --silent compile && node main.js",
+  "terraformModules": ["terraform-aws-modules/vpc/aws"],
+  "terraformProviders": ["aws@~> 2.0"]
+}
+```
+
+### Building Multiple Providers
+
+It's possible to build multiple providers or modules as well.
+
+```json
+{
+  "language": "typescript",
+  "app": "npm run --silent compile && node main.js",
+  "terraformProviders": [
+    "null",
+    "aws",
+    "google",
+    "azurerm",
+    "kubernetes",
+    "consul",
+    "vault",
+    "nomad"
+  ]
+}
+```
+
+### Building Providers in Custom Directory
+
+This generates the `aws` provider bindings in the folder `./imports`. This is used in the Python template to make it easier to reference the generated classes.
+
+```json
+{
+  "language": "python",
+  "app": "pipenv run ./main.py",
+  "terraformProviders": ["aws@~> 2.0"],
+  "codeMakerOutput": "imports"
+}
+```

website/docs/cdktf/concepts/fundamentals/functions.html.md

@@ -9,7 +9,6 @@ description: "Learn when to use built-in Terraform functions to transform or com
 
 Terraform provides a set of built-in functions that to transform and combine values within Terraform configurations. The [Terraform function documentation](https://www.terraform.io/docs/language/functions/index.html) contains a complete list. You can also use your editor autocompletion on the `Fn` object.
 
-
 ## Use Terraform functions
 
 We do not recommend using Terraform functions for inputs that are not tied to Terraform, such as environment variables, local files, etc. In those cases, it is easier and more efficient to do this using your chosen programming language.
@@ -29,5 +28,3 @@ new LoadBalancer(this, "lb", {
   subnet: Fn.cidrsubnet(Fn.element(vpc.listOfSubnets, 0), 4, 2),
 });
 ```
-
-

website/docs/cdktf/concepts/fundamentals/modules.html.md

@@ -39,17 +39,16 @@ For local modules, use the object format:
   "app": "npm run --silent compile && node main.js",
   "terraformProviders": ["aws@~> 2.0"],
   "terraformModules": [
-      {
-        "name": "my-local-module",
-        "source": "./path/to/local/terraform/module" // relative to cdktf.json file
-      }
-    ],
+    {
+      "name": "my-local-module",
+      "source": "./path/to/local/terraform/module" // relative to cdktf.json file
+    }
+  ]
 }
 ```
 
 -> **Note**: The [`cdktf.json` specification](../../../cdktf/cli-reference/configuration.html) contains syntax requirements for specifying a module version.
 
-
 ### Generate Module Bindings
 
 Go to the working directory and run `cdktf get` to create the appropriate module bindings in the `./.gen` directory automatically. You can then use them in your application.
@@ -58,8 +57,6 @@ Go to the working directory and run `cdktf get` to create the appropriate module
 TODO: Please provide an example of using a module in an application
 ```
 
-
-
 ## Work with Module Outputs
 
 Module [output values](/fundamentals/outputs.html) return data that can be used elsewhere in your configuration. CDK
@@ -125,7 +122,6 @@ class MyStack(TerraformStack):
         TerraformOutput(self, "dns-server", value=localModule.dns_server_output)
 ```
 
-
 ## Create Modules
 
 **TODO**: Is this another way that folks can get/use existing modules, or is it a way for them to create their own modules from inside a CDKTF App? I copyedited assuming that this was the latter, but please fix if I'm wrong.
@@ -134,10 +130,8 @@ Use `TerraformHclModule` to create Terraform modules using your chosen programmi
 
 -> **Note**: This doesn't have type safe inputs/outputs.
 
-
 **TODO**: Can we explain what happens to these when the code gets synthesized? Does this create this configuration in a separate directory?
 
-
 TypeScript example:
 
 **TODO**: Please make this into a real-world example, rather than using "test" and "foo".
@@ -159,4 +153,4 @@ const module = new TerraformHclModule(stack, "test", {
 new TestResource(stack, "resource", {
   name: module.getString("name"),
 });
-```
+```