docs: restructure and add new basic guides (wip)

docs/README.md

@@ -1,30 +1,35 @@
 # Table of Contents
 
-* [Basics](./basics/README.md)
-  * [Installation](./basics/installation.md)
-  * [Quick Start](./basics/quick-start.md)
-  * [Stack Graph](./basics/stack-graph.md)
+* [Installation](./installation.md)
+* [Quick Start](./quick-start.md)
+* [Stack Graph](./stack-graph.md)
 * [Using Garden](./using-garden/README.md)
-  * [Cloud Provider Set-up](./using-garden/cloud-provider-setup.md)
-  * [Configuration Files](./using-garden/configuration-files.md)
-  * [Container Modules](./using-garden/container-modules.md)
-  * [Development Workflows](./using-garden/development-workflows.md)
-  * [Helm Charts](./using-garden/using-helm-charts.md)
-  * [Hot Reload](./using-garden/hot-reload.md)
-  * [In-Cluster Building](./using-garden/in-cluster-building.md)
-  * [Local Kubernetes](./using-garden/local-kubernetes.md)
-  * [Remote Kubernetes](./using-garden/remote-kubernetes.md)
-  * [Remote Sources](./using-garden/using-remote-sources.md)
-  * [Terraform](./using-garden/terraform.md)
-  * [Variables and templating](./using-garden/variables-and-templating.md)
+  * [Creating a Project](./using-garden/creating-a-project.md)
+  * [Adding Modules](./using-garden/adding-modules.md)
+  * [Adding Services](./using-garden/adding-services.md)
+  * [Running Tests](./using-garden/running-tests.md)
+  * [Running Tasks](./using-garden/running-tasks.md)
+* [Guides](./guides/README.md)
+  * [Cloud Provider Set-up](./guides/cloud-provider-setup.md)
+  * [Configuration Files](./guides/configuration-files.md)
+  * [Container Modules](./guides/container-modules.md)
+  * [Development Workflows](./guides/development-workflows.md)
+  * [Helm Charts](./guides/using-helm-charts.md)
+  * [Hot Reload](./guides/hot-reload.md)
+  * [In-Cluster Building](./guides/in-cluster-building.md)
+  * [Local Kubernetes](./guides/local-kubernetes.md)
+  * [Remote Kubernetes](./guides/remote-kubernetes.md)
+  * [Remote Sources](./guides/using-remote-sources.md)
+  * [Terraform](./guides/terraform.md)
+  * [Variables and templating](./guides/variables-and-templating.md)
 * [Example Projects](./examples/README.md)
   * [Demo Project](./examples/demo-project.md)
   * [TLS Project](./examples/tls-project.md)
   * [Using Garden in CI](./examples/using-garden-in-ci.md)
 * [Reference](./reference/README.md)
+  * [Glossary](./reference/glossary.md)
   * [Commands Reference](./reference/commands.md)
   * [Config Files Reference](./reference/config.md)
-  * [Glossary](./reference/glossary.md)
   * [Module Types](./reference/module-types/README.md)
     * [Container](./reference/module-types/container.md)
     * [Exec](./reference/module-types/exec.md)

docs/examples/README.md

@@ -1,5 +1,6 @@
 ---
-order: 3
+order: 6
+title: Example Projects
 ---
 # Example Projects
 

docs/guides/README.md

@@ -0,0 +1,53 @@
+---
+order: 5
+title: Guides
+---
+# Guides
+
+## [Development Workflows](./development-workflows.md)
+
+In this article we discuss how to set up a new Garden project, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies.
+
+## [Configuration Files](./configuration-files.md)
+
+This one is all about Garden's configuration files—an overview of project and module configs, setting up services, and a primer on tests.
+
+## [Container Modules](./container-modules.md)
+
+One of the most commonly used module types for Garden is the `container` module type. This guide walks through its usage and configuration.
+
+## [Local Kubernetes](./local-kubernetes.md)
+
+Garden works great with local Kubernetes setups. Here you'll find installation and usage instructions for some
+common flavors of local Kubernetes setups, such as Minikube, Docker for Desktop and MicroK8s.
+
+## [Remote Kubernetes](./remote-kubernetes.md)
+
+Garden can also work smoothly with remote Kubernetes clusters. If you'd like to use a remote cluster, you may have some
+additional considerations and requirements. Take a look at this guide for details.
+
+## [In-cluster Building](./in-cluster-building.md)
+
+One of Garden's most powerful features is the ability to build images in your Kubernetes development cluster, thus
+avoiding the need for local Kubernetes clusters. This guide covers the requirements for in-cluster building and how
+to set it up.
+
+## [Cloud Provider Set-up](./cloud-provider-setup.md)
+
+Instructions for creating and configuring Kubernetes clusters with GKE (Google), AKS (Azure), EKS and kops (AWS), and how to connect to them with Garden.
+
+## [Using Helm charts](./using-helm-charts.md)
+
+The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts, in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts.
+
+## [Using Remote Sources](./using-remote-sources.md)
+
+Instructions for how to import code from remote repositories into a Garden project.
+
+## [Hot Reload](./hot-reload.md)
+
+This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create containers.
+
+## [Terraform](./terraform.md)
+
+This article discusses how to use the Terraform provider, for provisioning infrastructure as part of your Garden project.

docs/basics/installation.md → docs/installation.md

@@ -1,3 +1,7 @@
+---
+order: 1
+title: Installation
+---
 # Installation
 
 This guide will walk you through setting up the Garden framework.

docs/basics/quick-start.md → docs/quick-start.md

@@ -1,3 +1,8 @@
+---
+order: 2
+title: Quick Start
+---
+
 # Quick Start
 
 This guide will walk you through setting up the Garden framework. It assumes you already have Garden installed. If you don't, please check out our [installation guide](./installation.md).

docs/reference/README.md

@@ -1,5 +1,6 @@
 ---
-order: 4
+order: 7
+title: Reference
 ---
 # Reference
 

docs/reference/commands.md

@@ -1,4 +1,5 @@
 ---
+order: 2
 title: Commands Reference
 ---
 

docs/reference/config.md

@@ -1,4 +1,5 @@
 ---
+order: 3
 title: Config Files Reference
 ---
 

docs/reference/glossary.md

@@ -1,3 +1,8 @@
+---
+order: 1
+title: Glossary
+---
+
 # Glossary
 
 #### Environment

docs/reference/module-types/README.md

@@ -1,3 +1,8 @@
+---
+order: 4
+title: Module Types
+---
+
 # Module Types
 
 * [Exec](./exec.md)

docs/reference/providers/README.md

@@ -1,3 +1,7 @@
+---
+order: 5
+title: Providers
+---
 # Providers
 
 * [Kubernetes](./kubernetes.md)

docs/basics/stack-graph.md → docs/stack-graph.md

@@ -1,4 +1,5 @@
 ---
+order: 3
 title: Stack Graph
 ---
 # The Stack Graph

docs/troubleshooting.md

@@ -1,3 +1,8 @@
+---
+order: 8
+title: Troubleshooting
+---
+
 # Troubleshooting
 
 _This section could (obviously) use more work. Contributions are most appreciated!_

docs/using-garden/README.md

@@ -1,52 +1,6 @@
 ---
-order: 2
+order: 4
+title: Using Garden
 ---
-# Using Garden
 
-## [Development Workflows](./development-workflows.md)
-
-In this article we discuss how to set up a new Garden project, the basic development workflow, how Garden's providers work, and the basics of testing and dependencies.
-
-## [Configuration Files](./configuration-files.md)
-
-This one is all about Garden's configuration files—an overview of project and module configs, setting up services, and a primer on tests.
-
-## [Container Modules](./container-modules.md)
-
-One of the most commonly used module types for Garden is the `container` module type. This guide walks through its usage and configuration.
-
-## [Local Kubernetes](./local-kubernetes.md)
-
-Garden works great with local Kubernetes setups. Here you'll find installation and usage instructions for some
-common flavors of local Kubernetes setups, such as Minikube, Docker for Desktop and MicroK8s.
-
-## [Remote Kubernetes](./remote-kubernetes.md)
-
-Garden can also work smoothly with remote Kubernetes clusters. If you'd like to use a remote cluster, you may have some
-additional considerations and requirements. Take a look at this guide for details.
-
-## [In-cluster Building](./in-cluster-building.md)
-
-One of Garden's most powerful features is the ability to build images in your Kubernetes development cluster, thus
-avoiding the need for local Kubernetes clusters. This guide covers the requirements for in-cluster building and how
-to set it up.
-
-## [Cloud Provider Set-up](./cloud-provider-setup.md)
-
-Instructions for creating and configuring Kubernetes clusters with GKE (Google), AKS (Azure), EKS and kops (AWS), and how to connect to them with Garden.
-
-## [Using Helm charts](./using-helm-charts.md)
-
-The [Helm](https://helm.sh/) package manager is one of the most commonly used tools for managing Kubernetes manifests. Garden supports using your own Helm charts, alongside your container modules. This guide shows you how to use 3rd-party (or otherwise external) Helm charts, as well as your own charts, in your Garden project. We also go through how to configure tests, tasks and hot-reloading for your charts.
-
-## [Using Remote Sources](./using-remote-sources.md)
-
-Instructions for how to import code from remote repositories into a Garden project.
-
-## [Hot Reload](./hot-reload.md)
-
-This article discusses how to use hot reloading, so that you can update running services on the fly as you make changes to their code, without losing state and without having to destroy and re-create containers.
-
-## [Terraform](./terraform.md)
-
-This article discusses how to use the Terraform provider, for provisioning infrastructure as part of your Garden project.
+## TODO

docs/using-garden/adding-modules.md

@@ -0,0 +1,108 @@
+---
+order: 3
+title: Adding Modules
+---
+
+# Adding Modules
+
+Modules are the basic **unit of building** in Garden. They are usually the first thing you add after creating the project level configuration.
+
+A module can correspond to a Dockerfile and its associated code, a remote Docker image, a Helm chart, an OpenFaaS function, and more, all depending on the module type.
+
+Below is a simple example of a module's `garden.yml` (from the [`demo-project`]([https://github.com/garden-io/garden/tree/master/examples/demo-project](https://github.com/garden-io/garden/tree/master/examples/demo-project)) example project):
+
+```
+kind: Module
+name: backend
+description: Backend service container
+type: container
+services:
+    ...
+tasks:
+    ...
+tests:
+    ...
+```
+
+## How it Works
+
+A Garden project is usually split up into the project level `garden.yml` file and several module level configuration files:
+
+```console
+.
+├── garden.yml
+├── module-a
+│   ├── garden.yml
+│   └── ...
+├── module-b
+│   └── garden.yml
+│   └── ...
+├── module-c
+     └── garden.yml
+     └── ...
+```
+
+- It's also possible to [include several modules in the same `garden.yml` file]([https://docs.garden.io/using-garden/configuration-files#multiple-modules-in-the-same-file](https://docs.garden.io/using-garden/configuration-files#multiple-modules-in-the-same-file)) and/or with the project level configuration.
+
+Modules must have a type and different module types behave in different ways. For example, the `container` module type corresponds to a Docker image, either built from a local Dockerfile or pulled from a remote repository.
+
+Furthermore, modules can have `services` , `tests` and `tasks`.
+
+You use the `garden build` command to build your modules.
+
+Check out our [container module guide]([https://docs.garden.io/using-garden/container-modules](https://docs.garden.io/using-garden/container-modules)) for more information.
+
+## Modules in the Stack Graph
+
+Modules correspond to a **build** action in the Stack Graph.
+
+- Modules can depend on other modules (via a build dependency)
+- Tasks, tests, and services can depend on modules (via a build dependency)
+- Services implicitly depend on the build step of their parent module
+
+## Examples
+
+You can learn more about different module types in the [module type reference docs](#todo)
+
+### Container Module
+
+Below is the configuration for a simple container module. Here we're assuming that the source code is in the same directory as the `garden.yml` file.
+
+```yaml
+kind: Module
+name: backend
+description: Backend service container
+type: container
+```
+
+### Multiple Modules in the Same File
+
+In this example, we declare multiple container modules in the same file. We use the `include` directive to tell Garden where the source code for each modules resides.
+
+```yaml
+kind: Module
+name: backend
+description: Backend service container
+type: container
+include:
+  - ./backend
+---
+kind: Module
+name: frontend
+description: Frontend service container
+type: container
+include:
+  - ./frontend
+```
+
+### Container Module with a Remote Image
+
+In this example we use the `image` directive to include an external Docker image with the project. This module has no source code of it's own
+
+```yaml
+kind: Module
+name: backend
+description: Postgres DB container
+type: container
+image: postgres:11.4-alpine
+```