From d323391fb35a57d10ab730d9000f86fcc1d1dfe3 Mon Sep 17 00:00:00 2001 From: Jon Edvald Date: Fri, 21 Feb 2020 13:11:48 +0100 Subject: [PATCH] docs: update ToC layout --- .gitbook.yaml | 23 ++++ docs/README.md | 124 ++++++++++-------- docs/basics/README.md | 10 ++ docs/{ => basics}/installation.md | 10 +- docs/{ => basics}/quick-start.md | 6 +- docs/{ => basics}/stack-graph.md | 2 +- docs/examples/demo-project.md | 4 +- docs/guides/README.md | 4 - docs/guides/advanced/README.md | 9 ++ .../cert-manager-integration.md | 4 +- .../{ => advanced}/using-remote-sources.md | 0 docs/guides/configuration-files.md | 2 +- docs/guides/container-modules.md | 16 +-- docs/guides/development-workflows.md | 4 +- docs/guides/in-cluster-building.md | 10 +- docs/guides/remote-kubernetes.md | 4 +- docs/guides/terraform.md | 4 +- docs/guides/using-helm-charts.md | 4 +- docs/guides/variables-and-templating.md | 10 +- docs/misc/README.md | 9 ++ docs/{ => misc}/telemetry.md | 0 docs/{ => misc}/troubleshooting.md | 2 +- docs/reference/README.md | 8 +- docs/reference/commands.md | 4 +- docs/reference/config.md | 8 +- docs/reference/glossary.md | 4 +- docs/{ => reference}/module-types/README.md | 2 +- docs/{ => reference}/module-types/conftest.md | 4 +- .../{ => reference}/module-types/container.md | 18 +-- docs/{ => reference}/module-types/exec.md | 2 +- docs/{ => reference}/module-types/hadolint.md | 4 +- docs/{ => reference}/module-types/helm.md | 2 +- .../module-types/kubernetes.md | 5 +- .../module-types/maven-container.md | 14 +- docs/{ => reference}/module-types/openfaas.md | 2 +- .../module-types/persistentvolumeclaim.md | 4 +- .../{ => reference}/module-types/terraform.md | 2 +- docs/{ => reference}/providers/README.md | 2 +- .../providers/conftest-container.md | 10 +- .../providers/conftest-kubernetes.md | 4 +- docs/{ => reference}/providers/conftest.md | 6 +- docs/{ => reference}/providers/hadolint.md | 14 +- docs/{ => reference}/providers/kubernetes.md | 12 +- .../providers/local-kubernetes.md | 12 +- .../providers/maven-container.md | 8 +- docs/{ => reference}/providers/openfaas.md | 6 +- docs/{ => reference}/providers/terraform.md | 2 +- docs/reference/template-strings.md | 3 +- docs/using-garden/adding-modules.md | 4 +- docs/using-garden/adding-services.md | 4 +- docs/using-garden/creating-a-project.md | 2 +- docs/using-garden/running-tasks.md | 6 +- docs/using-garden/running-tests.md | 6 +- .../src/commands/create/create-module.ts | 5 +- garden-service/src/config/config-context.ts | 12 +- garden-service/src/docs/common.ts | 11 ++ garden-service/src/docs/generate.ts | 8 +- garden-service/src/docs/table-of-contents.ts | 22 +++- .../src/docs/templates/base-config.hbs | 8 +- .../src/docs/templates/commands.hbs | 4 +- .../src/docs/templates/module-type.hbs | 2 +- .../src/docs/templates/provider.hbs | 2 +- .../src/docs/templates/template-strings.hbs | 3 +- .../plugins/conftest/conftest-container.ts | 12 +- .../plugins/conftest/conftest-kubernetes.ts | 6 +- .../src/plugins/conftest/conftest.ts | 12 +- .../src/plugins/container/config.ts | 7 +- .../src/plugins/container/container.ts | 6 +- .../src/plugins/hadolint/hadolint.ts | 20 ++- .../src/plugins/kubernetes/kubernetes.ts | 16 +-- .../src/plugins/kubernetes/local/local.ts | 13 +- .../volumes/persistentvolumeclaim.ts | 4 +- .../maven-container/maven-container.ts | 11 +- .../src/plugins/openfaas/openfaas.ts | 8 +- .../test/unit/src/docs/table-of-contents.ts | 28 ++-- 75 files changed, 375 insertions(+), 290 deletions(-) create mode 100644 docs/basics/README.md rename docs/{ => basics}/installation.md (95%) rename docs/{ => basics}/quick-start.md (85%) rename docs/{ => basics}/stack-graph.md (98%) create mode 100644 docs/guides/advanced/README.md rename docs/guides/{ => advanced}/cert-manager-integration.md (94%) rename docs/guides/{ => advanced}/using-remote-sources.md (100%) create mode 100644 docs/misc/README.md rename docs/{ => misc}/telemetry.md (100%) rename docs/{ => misc}/troubleshooting.md (88%) rename docs/{ => reference}/module-types/README.md (97%) rename docs/{ => reference}/module-types/conftest.md (97%) rename docs/{ => reference}/module-types/container.md (98%) rename docs/{ => reference}/module-types/exec.md (99%) rename docs/{ => reference}/module-types/hadolint.md (98%) rename docs/{ => reference}/module-types/helm.md (99%) rename docs/{ => reference}/module-types/kubernetes.md (99%) rename docs/{ => reference}/module-types/maven-container.md (98%) rename docs/{ => reference}/module-types/openfaas.md (99%) rename docs/{ => reference}/module-types/persistentvolumeclaim.md (99%) rename docs/{ => reference}/module-types/terraform.md (99%) rename docs/{ => reference}/providers/README.md (97%) rename docs/{ => reference}/providers/conftest-container.md (87%) rename docs/{ => reference}/providers/conftest-kubernetes.md (95%) rename docs/{ => reference}/providers/conftest.md (83%) rename docs/{ => reference}/providers/hadolint.md (75%) rename docs/{ => reference}/providers/kubernetes.md (99%) rename docs/{ => reference}/providers/local-kubernetes.md (98%) rename docs/{ => reference}/providers/maven-container.md (78%) rename docs/{ => reference}/providers/openfaas.md (93%) rename docs/{ => reference}/providers/terraform.md (97%) diff --git a/.gitbook.yaml b/.gitbook.yaml index cc4ea460c9d..552764ebeab 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -1,3 +1,26 @@ structure: readme: README.md summary: docs/README.md + +redirects: + guides/using-remote-sources: guides/advanced/using-remote-sources.md + guides/cert-manager-integration: guides/advanced/cert-manager-integration.md + providers/conftest-container: reference/providers/conftest-container.md + providers/conftest-kubernetes: reference/providers/conftest-kubernetes.md + providers/conftest: reference/providers/conftest.md + providers/hadolint: reference/providers/hadolint.md + providers/kubernetes: reference/providers/kubernetes.md + providers/local-kubernetes: reference/providers/local-kubernetes.md + providers/maven-container: reference/providers/maven-container.md + providers/openfaas: reference/providers/openfaas.md + providers/terraform: reference/providers/terraform.md + module-types/conftest: reference/module-types/conftest.md + module-types/container: reference/module-types/container.md + module-types/exec: reference/module-types/exec.md + module-types/hadolint: reference/module-types/hadolint.md + module-types/helm: reference/module-types/helm.md + module-types/kubernetes: reference/module-types/kubernetes.md + module-types/maven-container: reference/module-types/maven-container.md + module-types/openfaas: reference/module-types/openfaas.md + module-types/persistentvolumeclaim: reference/module-types/persistentvolumeclaim.md + module-types/terraform: reference/module-types/terraform.md diff --git a/docs/README.md b/docs/README.md index 5259d3849b8..40611b5f7b9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,57 +1,71 @@ # Table of Contents -* [Installation](./installation.md) -* [Quick Start](./quick-start.md) -* [Stack Graph](./stack-graph.md) -* [Using Garden](./using-garden/README.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) - * [cert-manager Integration](./guides/cert-manager-integration.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) -* [Providers](./providers/README.md) - * [`conftest-container`](./providers/conftest-container.md) - * [`conftest-kubernetes`](./providers/conftest-kubernetes.md) - * [`conftest`](./providers/conftest.md) - * [`hadolint`](./providers/hadolint.md) - * [`kubernetes`](./providers/kubernetes.md) - * [`local-kubernetes`](./providers/local-kubernetes.md) - * [`maven-container`](./providers/maven-container.md) - * [`openfaas`](./providers/openfaas.md) - * [`terraform`](./providers/terraform.md) -* [Module Types](./module-types/README.md) - * [`conftest`](./module-types/conftest.md) - * [`container`](./module-types/container.md) - * [`exec`](./module-types/exec.md) - * [`hadolint`](./module-types/hadolint.md) - * [`helm`](./module-types/helm.md) - * [`kubernetes`](./module-types/kubernetes.md) - * [`maven-container`](./module-types/maven-container.md) - * [`openfaas`](./module-types/openfaas.md) - * [`persistentvolumeclaim`](./module-types/persistentvolumeclaim.md) - * [`terraform`](./module-types/terraform.md) -* [Reference](./reference/README.md) - * [Glossary](./reference/glossary.md) - * [Commands Reference](./reference/commands.md) - * [Config Files Reference](./reference/config.md) - * [Template Strings Reference](./reference/template-strings.md) -* [Troubleshooting](./troubleshooting.md) -* [Telemetry](./telemetry.md) +## 🌳 Basics + +* [Installation](./basics/installation.md) +* [Quick Start](./basics/quick-start.md) +* [Stack Graph](./basics/stack-graph.md) + +## 🌻 Using Garden + +* [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 + +* [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) +* [Terraform](./guides/terraform.md) +* [Variables and templating](./guides/variables-and-templating.md) +* [Advanced](./guides/advanced/README.md) + * [Remote Sources](./guides/advanced/using-remote-sources.md) + * [cert-manager Integration](./guides/advanced/cert-manager-integration.md) + +## 🌿 Example Projects + +* [Demo Project](./examples/demo-project.md) +* [TLS Project](./examples/tls-project.md) +* [Using Garden in CI](./examples/using-garden-in-ci.md) + +## 🌺 Reference + +* [Providers](./reference/providers/README.md) + * [`conftest-container`](./reference/providers/conftest-container.md) + * [`conftest-kubernetes`](./reference/providers/conftest-kubernetes.md) + * [`conftest`](./reference/providers/conftest.md) + * [`hadolint`](./reference/providers/hadolint.md) + * [`kubernetes`](./reference/providers/kubernetes.md) + * [`local-kubernetes`](./reference/providers/local-kubernetes.md) + * [`maven-container`](./reference/providers/maven-container.md) + * [`openfaas`](./reference/providers/openfaas.md) + * [`terraform`](./reference/providers/terraform.md) +* [Module Types](./reference/module-types/README.md) + * [`conftest`](./reference/module-types/conftest.md) + * [`container`](./reference/module-types/container.md) + * [`exec`](./reference/module-types/exec.md) + * [`hadolint`](./reference/module-types/hadolint.md) + * [`helm`](./reference/module-types/helm.md) + * [`kubernetes`](./reference/module-types/kubernetes.md) + * [`maven-container`](./reference/module-types/maven-container.md) + * [`openfaas`](./reference/module-types/openfaas.md) + * [`persistentvolumeclaim`](./reference/module-types/persistentvolumeclaim.md) + * [`terraform`](./reference/module-types/terraform.md) +* [Commands](./reference/commands.md) +* [Config Files](./reference/config.md) +* [Template Strings](./reference/template-strings.md) +* [Glossary](./reference/glossary.md) + +## ☘️ Misc + +* [Troubleshooting](./misc/troubleshooting.md) +* [Telemetry](./misc/telemetry.md) diff --git a/docs/basics/README.md b/docs/basics/README.md new file mode 100644 index 00000000000..fbaa449843d --- /dev/null +++ b/docs/basics/README.md @@ -0,0 +1,10 @@ +--- +order: 1 +title: Basics +--- + +# Basics + +* [Installation](./installation.md) +* [Quick Start](./quick-start.md) +* [Stack Graph](./stack-graph.md) diff --git a/docs/installation.md b/docs/basics/installation.md similarity index 95% rename from docs/installation.md rename to docs/basics/installation.md index 27ce12054f7..e4e9ac9c18b 100644 --- a/docs/installation.md +++ b/docs/basics/installation.md @@ -12,7 +12,7 @@ Please follow the guide for your operating system: * [Windows](#windows) * [Linux](#linux) -If you'd like to run Kubernetes locally, please see our [local Kubernetes guide](./guides/local-kubernetes.md) +If you'd like to run Kubernetes locally, please see our [local Kubernetes guide](../guides/local-kubernetes.md) for installation and usage information. If you want to install Garden from source, see the instructions in our [contributor guide](/~https://github.com/garden-io/garden/tree/master/CONTRIBUTING.md). @@ -77,14 +77,14 @@ To install Docker, Kubernetes and kubectl, we recommend Docker for Mac. Please refer to their [installation guide](https://docs.docker.com/engine/installation/) for how to download and install it (which is a pretty simple process). -If you'd like to use a local Kubernetes cluster, please refer to the [Local Kubernetes guide](./guides/local-kubernetes.md) -for further information. For remote clusters, take a look at the [Remote Kubernetes guide](./guides/remote-kubernetes.md). +If you'd like to use a local Kubernetes cluster, please refer to the [Local Kubernetes guide](../guides/local-kubernetes.md) +for further information. For remote clusters, take a look at the [Remote Kubernetes guide](../guides/remote-kubernetes.md). ## Windows You can run Garden on Windows 10 Home, Pro or Enterprise editions. -_Note: The Home edition doesn't support virtualization, but you can still use Garden if you're working with [remote Kubernetes](./guides/remote-kubernetes.md) and [in-cluster building](./guides/in-cluster-building.md)._ +_Note: The Home edition doesn't support virtualization, but you can still use Garden if you're working with [remote Kubernetes](../guides/remote-kubernetes.md) and [in-cluster building](../guides/in-cluster-building.md)._ To install the Garden CLI and its dependencies, please use our installation script. To run the script, open PowerShell as an administrator and run: @@ -137,7 +137,7 @@ To install Docker, please follow the instructions in the [official documentation ### Step 4 (optional): Local Kubernetes -If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](./guides/local-kubernetes.md) +If you'd like to use a local Kubernetes cluster, please refer to the [local Kubernetes guide](../guides/local-kubernetes.md) for installation and usage information. ## Using Garden with proxies diff --git a/docs/quick-start.md b/docs/basics/quick-start.md similarity index 85% rename from docs/quick-start.md rename to docs/basics/quick-start.md index 12bb6d0aa6e..66b17e2588b 100644 --- a/docs/quick-start.md +++ b/docs/basics/quick-start.md @@ -9,7 +9,7 @@ This guide will walk you through setting up the Garden framework. It assumes you ## Using the CLI -With the CLI installed, we can now try out a few commands using the [Demo Project](./examples/demo-project.md) from our [example projects](./examples/README.md). The example project consists of a couple of basic modules, each defining one service. +With the CLI installed, we can now try out a few commands using the [Demo Project](../examples/demo-project.md) from our [example projects](../examples/README.md). The example project consists of a couple of basic modules, each defining one service. _Note: Check whether Kubernetes is running with `kubectl version`. You should see both a `Client Version` and a `Server Version` in the response. If not, please start it up before proceeding._ @@ -75,8 +75,8 @@ garden dev Go ahead, leave it running and change one of the files in the project, then watch it re-build. -That's it for now. Check out our [Using Garden](./guides/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more. +That's it for now. Check out our [Using Garden](../guides/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more. ## Next steps -To see how a Garden project is configured from scratch check, out the [Demo Project](./examples/demo-project.md) guide for a more in-depth presentation. +To see how a Garden project is configured from scratch check, out the [Demo Project](../examples/demo-project.md) guide for a more in-depth presentation. diff --git a/docs/stack-graph.md b/docs/basics/stack-graph.md similarity index 98% rename from docs/stack-graph.md rename to docs/basics/stack-graph.md index d8fe3a28809..a19dd06bbbb 100644 --- a/docs/stack-graph.md +++ b/docs/basics/stack-graph.md @@ -71,4 +71,4 @@ Note here the first four fields, which are common across all module types—`kin Also notice that the `container` module explicitly declares a service, whereas the `helm` module does not. This is dictated by the module type. Containers often only need to be built (e.g. base images for other containers), or may contain multiple services. A Helm chart, however, is generally a single deployable so the provider makes the service implicit when configuring it. -For more details on how to configure your project, take a look at the [configuration guide](./guides/configuration-files.md). +For more details on how to configure your project, take a look at the [configuration guide](../guides/configuration-files.md). diff --git a/docs/examples/demo-project.md b/docs/examples/demo-project.md index 36ec1d36cec..b91f0eb158b 100644 --- a/docs/examples/demo-project.md +++ b/docs/examples/demo-project.md @@ -13,7 +13,7 @@ In what follows you'll learn how to: ## Before you get started -This tutorial assumes that you already have a running [installation of Garden](../installation.md). +This tutorial assumes that you already have a running [installation of Garden](../basics/installation.md). ## Clone the example repo @@ -76,7 +76,7 @@ Above, we've specified the name of our project and configured it to use the `loc ## Module configuration -Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../stack-graph.md#structure-and-terminology). +Now, let's turn to our services. Services live inside [modules](../reference/glossary.md#Module), and each module has its own `garden.yml` configuration file. You can read more about the difference between services and modules [here](../basics/stack-graph.md#structure-and-terminology). We'll start with the module for the `frontend`: diff --git a/docs/guides/README.md b/docs/guides/README.md index e7fbe6a98b7..8c8721779dc 100644 --- a/docs/guides/README.md +++ b/docs/guides/README.md @@ -41,10 +41,6 @@ Instructions for creating and configuring Kubernetes clusters with GKE (Google), 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. diff --git a/docs/guides/advanced/README.md b/docs/guides/advanced/README.md new file mode 100644 index 00000000000..c06e70e4f50 --- /dev/null +++ b/docs/guides/advanced/README.md @@ -0,0 +1,9 @@ +--- +order: 10000 +title: Advanced +--- + +# Advanced + +* [cert-manager integration](./cert-manager-integration.md) +* [Using Remote Sources](./using-remote-sources.md) diff --git a/docs/guides/cert-manager-integration.md b/docs/guides/advanced/cert-manager-integration.md similarity index 94% rename from docs/guides/cert-manager-integration.md rename to docs/guides/advanced/cert-manager-integration.md index 827bf2cb828..53599413254 100644 --- a/docs/guides/cert-manager-integration.md +++ b/docs/guides/advanced/cert-manager-integration.md @@ -2,7 +2,7 @@ When starting a new Kubernetes project or when maintaining your existing ones, dealing with the creation and renewal of TLS certificates can easily become a headache. A popular tool to help automate certficate generation and renewal is [cert-manager](/~https://github.com/jetstack/cert-manager). -The [kubernetes](./remote-kubernetes.md) and [local-kubernetes](./local-kubernetes.md) providers include an integration with cert-manager. The goal of the integration is to give you a head start when setting up TLS certificates for your project, providing an easy way to install it, and some sensible defaults. +The [kubernetes](../remote-kubernetes.md) and [local-kubernetes](../local-kubernetes.md) providers include an integration with cert-manager. The goal of the integration is to give you a head start when setting up TLS certificates for your project, providing an easy way to install it, and some sensible defaults. We don't aim to support all the features of cert-manager, but rather accommodate the most common use case, while still allowing full control of the underlying setup when needed. ## Requirements @@ -57,7 +57,7 @@ A valid email address is also required for Let's Encrypt certificate requests. ### Issuing your first certificate cert-manager is a powerful tool with a lot of different possible configurations. While integrating it with Garden we decided to start with an opinionated setup which should get you up to speed quickly, without thinking too much about configuration. -If/when you need specific settings or advanced use-cases, you can choose which certificates need to be managed by the integration and which you want to manage yourself using the [`tlsCertificates[].managedBy` config field](../providers/kubernetes.md#providerstlscertificatesmanagedby). +If/when you need specific settings or advanced use-cases, you can choose which certificates need to be managed by the integration and which you want to manage yourself using the [`tlsCertificates[].managedBy` config field](../../reference/providers/kubernetes.md#providerstlscertificatesmanagedby). #### Example diff --git a/docs/guides/using-remote-sources.md b/docs/guides/advanced/using-remote-sources.md similarity index 100% rename from docs/guides/using-remote-sources.md rename to docs/guides/advanced/using-remote-sources.md diff --git a/docs/guides/configuration-files.md b/docs/guides/configuration-files.md index 8f5e670d601..ef387b896d8 100644 --- a/docs/guides/configuration-files.md +++ b/docs/guides/configuration-files.md @@ -1,7 +1,7 @@ # Configuration Files Garden is configured via `garden.yml` configuration files, which Garden collects and compiles into a -[Stack Graph](../stack-graph.md) of your project. +[Stack Graph](../basics/stack-graph.md) of your project. The [project-wide](#project-configuration) `garden.yml` file should be located in the top-level directory of the project's Git repository. diff --git a/docs/guides/container-modules.md b/docs/guides/container-modules.md index c8638e84c3d..e8a00e05d0f 100644 --- a/docs/guides/container-modules.md +++ b/docs/guides/container-modules.md @@ -4,7 +4,7 @@ Garden includes a `container` module type, which provides a high-level abstracti `container` modules can be used to just _build_ container images, or they can specify deployable services through the optional `services` key, as well as `tasks` and `tests`. So you might in one scenario use a `container` module to both build and deploy services, and in another you might only build the image using a `container` module, and then refer to that image in a `helm` or `kubernetes` module. -Below we'll walk through some usage examples. For a full reference of the `container` module type, please take a look at the [reference](../module-types/container.md). +Below we'll walk through some usage examples. For a full reference of the `container` module type, please take a look at the [reference](../reference/module-types/container.md). _Note: Even though we've spent the most time on supporting Kubernetes, we've tried to design this module type in a way that makes it generically applicable to other container orchestrators as well, such as Docker Swarm, Docker Compose, AWS ECS etc. This will come in handy as we add more providers, that can then use the same module type._ @@ -83,7 +83,7 @@ services: ... ``` -This, first of all, tells Garden that it should deploy the built `frontend` container as a service with the same name. We also configure a health check, a couple of ingress endpoints, and specify that this service depends on the `backend` service. There is a number of other options, which you can find in the `container` module [reference](../module-types/container.md#services). +This, first of all, tells Garden that it should deploy the built `frontend` container as a service with the same name. We also configure a health check, a couple of ingress endpoints, and specify that this service depends on the `backend` service. There is a number of other options, which you can find in the `container` module [reference](../reference/module-types/container.md#services). If you need to use advanced (or otherwise very specific) features of the underlying platform, you may need to use more platform-specific module types (e.g. `kubernetes` or `helm`). The `container` module type is not intended to capture all those features. @@ -168,7 +168,7 @@ When you run `garden test` or `garden dev` we will run those tests. In both case The names and commands to run are of course completely up to you, but we suggest naming the test suites consistently across your different modules. -See the [reference](../module-types/container.md#tests) for all the configurable parameters for container tests. +See the [reference](../reference/module-types/container.md#tests) for all the configurable parameters for container tests. ## Running tasks @@ -193,7 +193,7 @@ Unlike tests, tasks can also be dependencies for services and other tasks. For e One thing to note, is that tasks should in most cases be _idempotent_, meaning that running the same task multiple times should be safe. -See the [reference](../module-types/container.md#tasks) for all the configurable parameters for container tasks. +See the [reference](../reference/module-types/container.md#tasks) for all the configurable parameters for container tasks. ## Referencing from other modules @@ -215,11 +215,11 @@ values: Here, we declare `my-image` as a dependency for the `my-service` Helm chart. In order for the Helm chart to be able to reference the built container image, we must provide the correct image name and version. -For a full list of keys that are available for the `container` module type, take a look at the [outputs reference](../module-types/container.md#outputs). +For a full list of keys that are available for the `container` module type, take a look at the [outputs reference](../reference/module-types/container.md#outputs). ## Mounting volumes -`container` services, tasks and tests can all mount volumes, using _volume modules_. One such is the [`persistentvolumeclaim` module type](../module-types/persistentvolumeclaim.md), supported by the `kubernetes` provider. To mount a volume, you need to define a volume module, and reference it using the `volumes` key on your services, tasks and/or tests. +`container` services, tasks and tests can all mount volumes, using _volume modules_. One such is the [`persistentvolumeclaim` module type](../reference/module-types/persistentvolumeclaim.md), supported by the `kubernetes` provider. To mount a volume, you need to define a volume module, and reference it using the `volumes` key on your services, tasks and/or tests. Example: @@ -252,10 +252,10 @@ This will mount the `my-volume` PVC at `/volume` in the `my-service` service whe Notice the `accessModes` field in the volume module above. The default storage classes in Kubernetes generally don't support being mounted by multiple Pods at the same time. If your volume module doesn't support the `ReadWriteMany` access mode, you must take care not to use the same volume in multiple services, tasks or tests, or multiple replicas. See [Shared volumes](#shared-volumes) below for how to share a single volume with multiple Pods. {% endhint %} -You can do the same for tests and tasks using the [`tests.volumes`](../module-types/container.md#testsvolumes) and [`tasks.volumes`](../module-types/container.md#tasksvolumes) fields. `persistentvolumeclaim` volumes can of course also be referenced in `kubernetes` and +You can do the same for tests and tasks using the [`tests.volumes`](../reference/module-types/container.md#testsvolumes) and [`tasks.volumes`](../reference/module-types/container.md#tasksvolumes) fields. `persistentvolumeclaim` volumes can of course also be referenced in `kubernetes` and `helm` modules, since they are deployed as standard PersistentVolumeClaim resources. -Take a look at the [`persistentvolumeclaim` module type](../module-types/persistentvolumeclaim.md) and [`container` module](../module-types/container.md#servicesvolumes) docs for more details. +Take a look at the [`persistentvolumeclaim` module type](../reference/module-types/persistentvolumeclaim.md) and [`container` module](../reference/module-types/container.md#servicesvolumes) docs for more details. ### Shared volumes diff --git a/docs/guides/development-workflows.md b/docs/guides/development-workflows.md index 2ceea2a199b..7ef78024942 100644 --- a/docs/guides/development-workflows.md +++ b/docs/guides/development-workflows.md @@ -1,7 +1,7 @@ # Development Workflows -Now that you've had a glimpse of the basic Garden commands in the [Quick Start](../quick-start.md) guide, and -learned about the [Stack Graph](../stack-graph.md), let's go through some typical Garden workflows. +Now that you've had a glimpse of the basic Garden commands in the [Quick Start](../basics/quick-start.md) guide, and +learned about the [Stack Graph](../basics/stack-graph.md), let's go through some typical Garden workflows. We'll keep using the [Demo Project](../examples/demo-project.md) example, but the same principles will apply for most Garden projects. diff --git a/docs/guides/in-cluster-building.md b/docs/guides/in-cluster-building.md index c22a64d59dc..07eae493567 100644 --- a/docs/guides/in-cluster-building.md +++ b/docs/guides/in-cluster-building.md @@ -30,8 +30,8 @@ Specifically, the clusters need the following: - Support for `PersistentVolumeClaim`s and enough disk space for layer caches and the in-cluster image registry. You can—_and should_—adjust the allocated resources and storage in the provider configuration, under -[resources](../providers/kubernetes.md#providersresources) and -[storage](../providers/kubernetes.md#providersstorage). See the individual modes below as well for more +[resources](../reference/providers/kubernetes.md#providersresources) and +[storage](../reference/providers/kubernetes.md#providersstorage). See the individual modes below as well for more information on how to allocate resources appropriately. ## Build modes @@ -67,7 +67,7 @@ In this mode, builds are executed as follows: After enabling this mode (we currently still default to the `local-docker` mode), you will need to run `garden plugins kubernetes cluster-init --env=` for each applicable environment, in order to install the required cluster-wide services. Those services include the Docker daemon itself, as well as an image registry, a sync service for receiving build contexts, two persistent volumes, an NFS volume provisioner for one of those volumes, and a couple of small utility services. Make sure your cluster has enough resources and storage to support the required services, and keep in mind that these -services are shared across all users of the cluster. Please look at the [resources](../providers/kubernetes.md#providersresources) and [storage](../providers/kubernetes.md#providersstorage) sections in the provider reference for +services are shared across all users of the cluster. Please look at the [resources](../reference/providers/kubernetes.md#providersresources) and [storage](../reference/providers/kubernetes.md#providersstorage) sections in the provider reference for details. ### Kaniko @@ -84,7 +84,7 @@ The trade-off is generally in performance, at least for the moment, partly becau cache layers. There are also some known issues and incompatibilities, so your mileage may vary. Note the difference in how resources for the builder are allocated. See the -[builder resources](../providers/kubernetes.md#providersresourcesbuilder) reference for details. +[builder resources](../reference/providers/kubernetes.md#providersresourcesbuilder) reference for details. ### Local Docker @@ -141,7 +141,7 @@ FROM my-private-registry.com/my-image:tag where `my-private-registry.com` requires authorization. -For this to work, you need to create a registry secret in your cluster (see [this guide](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for how to create the secret) and then configure the [imagePullSecrets](../providers/kubernetes.md#providersimagepullsecrets) field in your `kubernetes` provider configuration: +For this to work, you need to create a registry secret in your cluster (see [this guide](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) for how to create the secret) and then configure the [imagePullSecrets](../reference/providers/kubernetes.md#providersimagepullsecrets) field in your `kubernetes` provider configuration: ```yaml kind: Project diff --git a/docs/guides/remote-kubernetes.md b/docs/guides/remote-kubernetes.md index 712902a7618..aa284a18bd6 100644 --- a/docs/guides/remote-kubernetes.md +++ b/docs/guides/remote-kubernetes.md @@ -130,14 +130,14 @@ to your registry's documentation on how to do that (for Docker Hub you simply ru ### Ingress, TLS and DNS -By default, Garden will not install an ingress controller for remote environments. This can be toggled by setting the [`setupIngressController` flag](../providers/kubernetes.md#providerssetupingresscontroller) to `nginx`. Alternatively, you can set up your own ingress controller, e.g. using [Traefik](https://traefik.io/), [Ambassador](https://www.getambassador.io/) or [Istio](https://istio.io/). You can find examples for [using Garden with Ambassador](/~https://github.com/garden-io/garden/tree/v0.11.3/examples/ambassador) and [with Istio](/~https://github.com/garden-io/garden/tree/v0.11.3/examples/istio) in our [examples directory](/~https://github.com/garden-io/garden/tree/v0.11.3/examples). +By default, Garden will not install an ingress controller for remote environments. This can be toggled by setting the [`setupIngressController` flag](../reference/providers/kubernetes.md#providerssetupingresscontroller) to `nginx`. Alternatively, you can set up your own ingress controller, e.g. using [Traefik](https://traefik.io/), [Ambassador](https://www.getambassador.io/) or [Istio](https://istio.io/). You can find examples for [using Garden with Ambassador](/~https://github.com/garden-io/garden/tree/v0.11.3/examples/ambassador) and [with Istio](/~https://github.com/garden-io/garden/tree/v0.11.3/examples/istio) in our [examples directory](/~https://github.com/garden-io/garden/tree/v0.11.3/examples). You'll also need to point one or more DNS entries to your cluster, and configure a TLS certificate for the hostnames you will expose for ingress. _How you configure DNS and prepare the certificates will depend on how you manage DNS and certificates in general, so we won't cover that in detail here._ -If you are using [cert-manager](/~https://github.com/jetstack/cert-manager) (or would like to use it) to manage your TLS certificates, you may want to check out the [cert-manager integration](../guides/cert-manager-integration.md), which helps to automate some of the otherwise manual work involved in managing certificates. +If you are using [cert-manager](/~https://github.com/jetstack/cert-manager) (or would like to use it) to manage your TLS certificates, you may want to check out the [cert-manager integration](./advanced/cert-manager-integration.md), which helps to automate some of the otherwise manual work involved in managing certificates. If you are manually creating or obtaining the certificates (and you have the `.crt` and `.key` files), create a [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) for each cert in the cluster so diff --git a/docs/guides/terraform.md b/docs/guides/terraform.md index 6606c8a0e03..59770854157 100644 --- a/docs/guides/terraform.md +++ b/docs/guides/terraform.md @@ -80,10 +80,10 @@ services: Here we imagine a Terraform stack that has a `my-database-uri` output, that we then supply to `my-service` via the `DATABASE_URI` environment variable. -Much like other modules, you can also reference Terraform definitions in other repositories using the `repositoryUrl` key. See the [Remote Sources](./using-remote-sources.md) guide for details. +Much like other modules, you can also reference Terraform definitions in other repositories using the `repositoryUrl` key. See the [Remote Sources](./advanced/using-remote-sources.md) guide for details. ## Next steps -Check out the [terraform-gke example](/~https://github.com/garden-io/garden/tree/v0.11.3/examples/terraform-gke) project. Also take a look at the [Terraform provider reference](../providers/terraform.md) and the [Terraform module type reference](../module-types/terraform.md) for details on all the configuration parameters. +Check out the [terraform-gke example](/~https://github.com/garden-io/garden/tree/v0.11.3/examples/terraform-gke) project. Also take a look at the [Terraform provider reference](../reference/providers/terraform.md) and the [Terraform module type reference](../reference/module-types/terraform.md) for details on all the configuration parameters. If you're having issues with Terraform itself, please refer to the [official docs](https://www.terraform.io/docs/index.html). diff --git a/docs/guides/using-helm-charts.md b/docs/guides/using-helm-charts.md index bd140b5f511..20c1a7462e6 100644 --- a/docs/guides/using-helm-charts.md +++ b/docs/guides/using-helm-charts.md @@ -4,7 +4,7 @@ The [Helm](https://helm.sh/) package manager is one of the most commonly used to In this guide we'll be using the [vote-helm](/~https://github.com/garden-io/garden/tree/v0.11.3/examples/vote-helm) project. If you prefer to just check out a complete example, the project itself is also a good resource. -You may also want to check out the full [helm module reference](../module-types/helm.md). +You may also want to check out the full [helm module reference](../reference/module-types/helm.md). _Note: If you only need a way to deploy some Kubernetes manifests and don't need all the features of Helm, you can_ _use the simpler `kubernetes` module type instead. Check out the_ @@ -306,7 +306,7 @@ You can define a remote environment as a `production` environment by setting the ## Next steps -Check out the full [helm module reference](../module-types/helm.md) for more details, and the +Check out the full [helm module reference](../reference/module-types/helm.md) for more details, and the [vote-helm](/~https://github.com/garden-io/garden/tree/master/examples/vote-helm) example project for a full project that showcases Garden's Helm support. diff --git a/docs/guides/variables-and-templating.md b/docs/guides/variables-and-templating.md index 1e0f86f58d8..974b071b290 100644 --- a/docs/guides/variables-and-templating.md +++ b/docs/guides/variables-and-templating.md @@ -191,7 +191,7 @@ services: Providers often expose useful variables that other provider configs and modules can reference, under `${providers..outputs.}`. Each provider exposes different outputs, and some providers have dynamic output keys depending on their configuration. -For example, you may want to reference the app namespace from the [Kubernetes provider](../providers/kubernetes.md) in module configs: +For example, you may want to reference the app namespace from the [Kubernetes provider](../reference/providers/kubernetes.md) in module configs: ```yaml kind: Module @@ -212,13 +212,13 @@ services: DATABASE_URL: `${providers.terraform.outputs.database_url}` # <- resolves the "database_url" stack output ``` -Check out the individual [provider reference](../providers/README.md) guides for details on what outputs each provider exposes. +Check out the individual [provider reference](../reference/providers/README.md) guides for details on what outputs each provider exposes. ## Module outputs Modules often output useful information, that other modules can reference (provider configs cannot reference module outputs). Every module also exposes certain keys, like the module version. -For example, you may want to reference the image name and version of a [container module](../module-types/container.md): +For example, you may want to reference the image name and version of a [container module](../reference/module-types/container.md): ```yaml kind: Module @@ -229,7 +229,7 @@ values: image: `${modules.my-image.outputs.deployment-image-name}:${modules.my-image.version}` ``` -Check out the individual [module type reference](../module-types/README.md) guides for details on what outputs each module type exposes. +Check out the individual [module type reference](../reference/module-types/README.md) guides for details on what outputs each module type exposes. ## Runtime outputs @@ -263,4 +263,4 @@ Different module types expose different output keys for their services and tasks ## Next steps -For a full reference of the keys available in template strings, please look at the [Template Strings Reference](../reference/template-strings.md), as well as individual [providers](../providers/README.md) for provider outputs, and [module types](../module-types/README.md) for module and runtime output keys. +For a full reference of the keys available in template strings, please look at the [Template Strings Reference](../reference/template-strings.md), as well as individual [providers](../reference/providers/README.md) for provider outputs, and [module types](../reference/module-types/README.md) for module and runtime output keys. diff --git a/docs/misc/README.md b/docs/misc/README.md new file mode 100644 index 00000000000..d484bc94bca --- /dev/null +++ b/docs/misc/README.md @@ -0,0 +1,9 @@ +--- +order: 99 +title: Misc +--- + +# Basics + +* [Troubleshooting](./troubleshooting.md) +* [Telemetry](./telemetry.md) diff --git a/docs/telemetry.md b/docs/misc/telemetry.md similarity index 100% rename from docs/telemetry.md rename to docs/misc/telemetry.md diff --git a/docs/troubleshooting.md b/docs/misc/troubleshooting.md similarity index 88% rename from docs/troubleshooting.md rename to docs/misc/troubleshooting.md index ab829fb8e10..3986b0ad0d8 100644 --- a/docs/troubleshooting.md +++ b/docs/misc/troubleshooting.md @@ -11,7 +11,7 @@ _This section could (obviously) use more work. Contributions are most appreciate This issue often comes up on Linux, and in other scenarios where the filesystem doesn't support event-based file watching. -Thankfully, you can in most cases avoid this problem using the `modules.exclude` field in your project config, and/or the `exclude` field in your individual module configs. See the [Including/excluding files and directories](./guides/configuration-files.md#includingexcluding-files-and-directories) section in our Configuration Files guide for details. +Thankfully, you can in most cases avoid this problem using the `modules.exclude` field in your project config, and/or the `exclude` field in your individual module configs. See the [Including/excluding files and directories](../guides/configuration-files.md#includingexcluding-files-and-directories) section in our Configuration Files guide for details. ## I'm getting an "EPERM: operation not permitted, rename..." error on Windows diff --git a/docs/reference/README.md b/docs/reference/README.md index 4d7652164b1..d404b2ae532 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -4,7 +4,9 @@ title: Reference --- # Reference +* [Providers](./providers/README.md) +* [Module Types](./module-types/README.md) +* [Commands](./commands.md) +* [Config Files](./config.md) +* [Template Strings](./template-strings.md) * [Glossary](./glossary.md) -* [Commands Reference](./commands.md) -* [Config Files Reference](./config.md) -* [Template Strings Reference](./template-strings.md) diff --git a/docs/reference/commands.md b/docs/reference/commands.md index c5e3b65e259..8d84da9a8b2 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -1,6 +1,6 @@ --- -order: 2 -title: Commands Reference +order: 3 +title: Commands --- ## Garden CLI commands diff --git a/docs/reference/config.md b/docs/reference/config.md index dc22d44ca9e..725a9783497 100644 --- a/docs/reference/config.md +++ b/docs/reference/config.md @@ -1,6 +1,6 @@ --- -order: 3 -title: Config Files Reference +order: 4 +title: Config Files --- # garden.yml reference @@ -12,9 +12,9 @@ The reference is divided into four sections. The [first section](#project-yaml-s The [third section](#module-yaml-schema) contains the module level YAML schema, and the [fourth section](#module-configuration-keys) describes each individual schema key for the module level configuration. -Note that individual providers, e.g. `kubernetes`, add their own project level configuration keys. The provider types are listed on the [Providers page](../providers/README.md). +Note that individual providers, e.g. `kubernetes`, add their own project level configuration keys. The provider types are listed on the [Providers page](../reference/providers/README.md). -Likewise, individual module types, e.g. `container`, add additional configuration keys at the module level. Module types are listed on the [Module Types page](../module-types/README.md). +Likewise, individual module types, e.g. `container`, add additional configuration keys at the module level. Module types are listed on the [Module Types page](../reference/module-types/README.md). Please refer to those for more details on provider and module configuration. diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index 071ad1da1b6..f586ce8eda0 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -1,5 +1,5 @@ --- -order: 1 +order: 6 title: Glossary --- @@ -39,7 +39,7 @@ For a comprehensive list of providers available in Garden, check out the [Refere #### Service The unit of deployment in Garden. Services are defined in their parent [module](#module)'s `garden.yml`, each -exposing [one or more ingress endpoints](../module-types/container.md#servicesingresses). +exposing [one or more ingress endpoints](../reference/module-types/container.md#servicesingresses). Services may depend on services defined in other modules, in which case those services will be deployed first, and their deployment output made available to the requiring service's deploy step. diff --git a/docs/module-types/README.md b/docs/reference/module-types/README.md similarity index 97% rename from docs/module-types/README.md rename to docs/reference/module-types/README.md index 726a42e8986..d93c9c0215e 100644 --- a/docs/module-types/README.md +++ b/docs/reference/module-types/README.md @@ -1,5 +1,5 @@ --- -order: 7 +order: 2 title: Module Types --- diff --git a/docs/module-types/conftest.md b/docs/reference/module-types/conftest.md similarity index 97% rename from docs/module-types/conftest.md rename to docs/reference/module-types/conftest.md index 804ef9140cb..ab5bcb92e89 100644 --- a/docs/module-types/conftest.md +++ b/docs/reference/module-types/conftest.md @@ -10,12 +10,12 @@ tocTitle: "`conftest`" Creates a test that runs `conftest` on the specified files, with the specified (or default) policy and namespace. -> Note: In many cases, you'll let specific conftest providers (e.g. [`conftest-container`](https://docs.garden.io/providers/conftest-container) and [`conftest-kubernetes`](https://docs.garden.io/providers/conftest-kubernetes) create this module type automatically, but you may in some cases want or need to manually specify files to test. +> Note: In many cases, you'll let specific conftest providers (e.g. [`conftest-container`](https://docs.garden.io/reference/module-types/conftest-container) and [`conftest-kubernetes`](https://docs.garden.io/reference/module-types/conftest-kubernetes) create this module type automatically, but you may in some cases want or need to manually specify files to test. See the [conftest docs](/~https://github.com/instrumenta/conftest) for details on how to configure policies. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/module-types/container.md b/docs/reference/module-types/container.md similarity index 98% rename from docs/module-types/container.md rename to docs/reference/module-types/container.md index 441d45f586f..c316a2dc455 100644 --- a/docs/module-types/container.md +++ b/docs/reference/module-types/container.md @@ -12,11 +12,11 @@ You may also optionally specify services to deploy, tasks or tests to run inside Note that the runtime services have somewhat limited features in this module type. For example, you cannot specify replicas for redundancy, and various platform-specific options are not included. For those, look at -other module types like [helm](https://docs.garden.io/module-types/helm) or -[kubernetes](https://docs.garden.io/module-types/kubernetes). +other module types like [helm](https://docs.garden.io/reference/module-types/helm) or +[kubernetes](https://docs.garden.io/reference/module-types/kubernetes). Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. @@ -312,7 +312,7 @@ services: # The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will # depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim - # module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. + # module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. # # When a `module` is specified, the referenced module/volume will be automatically configured as a runtime # dependency of this service, as well as a build dependency of this module. @@ -380,7 +380,7 @@ tests: # The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will # depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim - # module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. + # module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. # # When a `module` is specified, the referenced module/volume will be automatically configured as a runtime # dependency of this service, as well as a build dependency of this module. @@ -464,7 +464,7 @@ tasks: # The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will # depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim - # module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. + # module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. # # When a `module` is specified, the referenced module/volume will be automatically configured as a runtime # dependency of this service, as well as a build dependency of this module. @@ -1320,7 +1320,7 @@ services: [services](#services) > [volumes](#servicesvolumes) > module -The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. +The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. When a `module` is specified, the referenced module/volume will be automatically configured as a runtime dependency of this service, as well as a build dependency of this module. @@ -1557,7 +1557,7 @@ tests: [tests](#tests) > [volumes](#testsvolumes) > module -The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. +The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. When a `module` is specified, the referenced module/volume will be automatically configured as a runtime dependency of this service, as well as a build dependency of this module. @@ -1815,7 +1815,7 @@ tasks: [tasks](#tasks) > [volumes](#tasksvolumes) > module -The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. +The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. When a `module` is specified, the referenced module/volume will be automatically configured as a runtime dependency of this service, as well as a build dependency of this module. diff --git a/docs/module-types/exec.md b/docs/reference/module-types/exec.md similarity index 99% rename from docs/module-types/exec.md rename to docs/reference/module-types/exec.md index de45b49d4dc..bfd19cb30f6 100644 --- a/docs/module-types/exec.md +++ b/docs/reference/module-types/exec.md @@ -19,7 +19,7 @@ This means that include/exclude filters and ignore files are not applied to loca filtering is done during the sync. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/module-types/hadolint.md b/docs/reference/module-types/hadolint.md similarity index 98% rename from docs/module-types/hadolint.md rename to docs/reference/module-types/hadolint.md index dee2248dd40..a4a3eaa1887 100644 --- a/docs/module-types/hadolint.md +++ b/docs/reference/module-types/hadolint.md @@ -9,7 +9,7 @@ tocTitle: "`hadolint`" Runs `hadolint` on the specified Dockerfile. -> Note: In most cases, you'll let the [provider](https://docs.garden.io/providers/hadolint) create this module type automatically, but you may in some cases want or need to manually specify a Dockerfile to lint. +> Note: In most cases, you'll let the [provider](https://docs.garden.io/reference/providers/hadolint) create this module type automatically, but you may in some cases want or need to manually specify a Dockerfile to lint. To configure `hadolint`, you can use `.hadolint.yaml` config files. For each test, we first look for one in the module root. If none is found there, we check the project root, and if none is there we fall back to default @@ -18,7 +18,7 @@ configuration. Note that for reasons of portability, we do not fall back to glob See the [hadolint docs](/~https://github.com/hadolint/hadolint#configure) for details on how to configure it. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/module-types/helm.md b/docs/reference/module-types/helm.md similarity index 99% rename from docs/module-types/helm.md rename to docs/reference/module-types/helm.md index 5b58b517dc2..1df243b25a5 100644 --- a/docs/module-types/helm.md +++ b/docs/reference/module-types/helm.md @@ -11,7 +11,7 @@ Specify a Helm chart (either in your repository or remote from a registry) to de Refer to the [Helm guide](https://docs.garden.io/guides/using-helm-charts) for usage instructions. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/module-types/kubernetes.md b/docs/reference/module-types/kubernetes.md similarity index 99% rename from docs/module-types/kubernetes.md rename to docs/reference/module-types/kubernetes.md index e3f2e608aa2..51aa41a85a8 100644 --- a/docs/module-types/kubernetes.md +++ b/docs/reference/module-types/kubernetes.md @@ -15,11 +15,10 @@ one or more files with existing manifests. Note that if you include the manifests in the `garden.yml` file, you can use [template strings](https://docs.garden.io/guides/variables-and-templating) to interpolate values into the manifests. -If you need more advanced templating features you can use the -[helm](https://docs.garden.io/module-types/helm) module type. +If you need more advanced templating features you can use the [helm](https://docs.garden.io/reference/module-types/helm) module type. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/module-types/maven-container.md b/docs/reference/module-types/maven-container.md similarity index 98% rename from docs/module-types/maven-container.md rename to docs/reference/module-types/maven-container.md index 5ec3f936264..a3bca0dd300 100644 --- a/docs/module-types/maven-container.md +++ b/docs/reference/module-types/maven-container.md @@ -21,7 +21,7 @@ To use it, make sure to add the `maven-container` provider to your project confi The provider will automatically fetch and cache Maven and the appropriate OpenJDK version ahead of building. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. @@ -310,7 +310,7 @@ services: # The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will # depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim - # module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. + # module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. # # When a `module` is specified, the referenced module/volume will be automatically configured as a runtime # dependency of this service, as well as a build dependency of this module. @@ -378,7 +378,7 @@ tests: # The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will # depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim - # module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. + # module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. # # When a `module` is specified, the referenced module/volume will be automatically configured as a runtime # dependency of this service, as well as a build dependency of this module. @@ -462,7 +462,7 @@ tasks: # The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will # depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim - # module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. + # module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. # # When a `module` is specified, the referenced module/volume will be automatically configured as a runtime # dependency of this service, as well as a build dependency of this module. @@ -1328,7 +1328,7 @@ services: [services](#services) > [volumes](#servicesvolumes) > module -The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. +The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. When a `module` is specified, the referenced module/volume will be automatically configured as a runtime dependency of this service, as well as a build dependency of this module. @@ -1565,7 +1565,7 @@ tests: [tests](#tests) > [volumes](#testsvolumes) > module -The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. +The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. When a `module` is specified, the referenced module/volume will be automatically configured as a runtime dependency of this service, as well as a build dependency of this module. @@ -1823,7 +1823,7 @@ tasks: [tasks](#tasks) > [volumes](#tasksvolumes) > module -The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/module-types/persistentvolumeclaim), for example. +The name of a _volume module_ that should be mounted at `containerPath`. The supported module types will depend on which provider you are using. The `kubernetes` provider supports the [persistentvolumeclaim module](https://docs.garden.io/reference/module-types/persistentvolumeclaim), for example. When a `module` is specified, the referenced module/volume will be automatically configured as a runtime dependency of this service, as well as a build dependency of this module. diff --git a/docs/module-types/openfaas.md b/docs/reference/module-types/openfaas.md similarity index 99% rename from docs/module-types/openfaas.md rename to docs/reference/module-types/openfaas.md index 542be6782b3..c50aec1f302 100644 --- a/docs/module-types/openfaas.md +++ b/docs/reference/module-types/openfaas.md @@ -11,7 +11,7 @@ Deploy a [OpenFaaS](https://www.openfaas.com/) function using Garden. Requires t to be configured. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/module-types/persistentvolumeclaim.md b/docs/reference/module-types/persistentvolumeclaim.md similarity index 99% rename from docs/module-types/persistentvolumeclaim.md rename to docs/reference/module-types/persistentvolumeclaim.md index 1ae120caa07..e5073976edb 100644 --- a/docs/module-types/persistentvolumeclaim.md +++ b/docs/reference/module-types/persistentvolumeclaim.md @@ -7,12 +7,12 @@ tocTitle: "`persistentvolumeclaim`" ## Description -Creates a [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) in your namespace, that can be referenced and mounted by other resources and [container modules](https://docs.garden.io/module-types/container). +Creates a [PersistentVolumeClaim](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) in your namespace, that can be referenced and mounted by other resources and [container modules](https://docs.garden.io/reference/module-types/container). See the [Mounting volumes](https://docs.garden.io/guides/container-modules#mounting-volumes) guide for more info and usage examples. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/module-types/terraform.md b/docs/reference/module-types/terraform.md similarity index 99% rename from docs/module-types/terraform.md rename to docs/reference/module-types/terraform.md index bc8d14c5f4b..07f1b80655d 100644 --- a/docs/module-types/terraform.md +++ b/docs/reference/module-types/terraform.md @@ -25,7 +25,7 @@ See the [Terraform guide](https://docs.garden.io/guides/terraform) for a high-le provider. Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/README.md b/docs/reference/providers/README.md similarity index 97% rename from docs/providers/README.md rename to docs/reference/providers/README.md index 7005af0ffa3..05568c38123 100644 --- a/docs/providers/README.md +++ b/docs/reference/providers/README.md @@ -1,5 +1,5 @@ --- -order: 6 +order: 1 title: Providers --- diff --git a/docs/providers/conftest-container.md b/docs/reference/providers/conftest-container.md similarity index 87% rename from docs/providers/conftest-container.md rename to docs/reference/providers/conftest-container.md index 6cc33ec4367..f1fcc23d184 100644 --- a/docs/providers/conftest-container.md +++ b/docs/reference/providers/conftest-container.md @@ -7,15 +7,11 @@ tocTitle: "`conftest-container`" ## Description -This provider automatically generates [conftest modules](https://docs.garden.io/module-types/conftest) for `container` modules -in your project. A `conftest` module is created for each `container` module that includes a Dockerfile that -can be validated. +This provider automatically generates [conftest modules](https://docs.garden.io/reference/module-types/conftest) for `container` modules in your project. A `conftest` module is created for each `container` module that includes a Dockerfile that can be validated. -Simply add this provider to your project configuration, and configure your policies. Check out the below -reference for how to configure default policies, default namespaces, and test failure thresholds for the generated -modules. +Simply add this provider to your project configuration, and configure your policies. Check out the below reference for how to configure default policies, default namespaces, and test failure thresholds for the generated modules. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/conftest-kubernetes.md b/docs/reference/providers/conftest-kubernetes.md similarity index 95% rename from docs/providers/conftest-kubernetes.md rename to docs/reference/providers/conftest-kubernetes.md index 3431d5a1f01..29dbabc4f72 100644 --- a/docs/providers/conftest-kubernetes.md +++ b/docs/reference/providers/conftest-kubernetes.md @@ -7,7 +7,7 @@ tocTitle: "`conftest-kubernetes`" ## Description -This provider automatically generates [conftest modules](https://docs.garden.io/module-types/conftest) for `kubernetes` and +This provider automatically generates [conftest modules](https://docs.garden.io/reference/module-types/conftest) for `kubernetes` and `helm` modules in your project. A `conftest` module is created for each of those module types. Simply add this provider to your project configuration, and configure your policies. Check out the below @@ -17,7 +17,7 @@ modules. See the [conftest example project](/~https://github.com/garden-io/garden/tree/master/examples/conftest) for a simple usage example. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/conftest.md b/docs/reference/providers/conftest.md similarity index 83% rename from docs/providers/conftest.md rename to docs/reference/providers/conftest.md index 848c6970498..42f0ba77e09 100644 --- a/docs/providers/conftest.md +++ b/docs/reference/providers/conftest.md @@ -9,11 +9,11 @@ tocTitle: "`conftest`" This provider allows you to validate your configuration files against policies that you specify, using the [conftest tool](/~https://github.com/instrumenta/conftest) and Open Policy Agent rego query files. The provider creates a module type of the same name, which allows you to specify files to validate. Each module then creates a Garden test that becomes part of your Stack Graph. -Note that, in many cases, you'll actually want to use more specific providers that can automatically configure your `conftest` modules, e.g. the [`conftest-container`](https://docs.garden.io/providers/conftest-container) and/or [`conftest-kubernetes`](https://docs.garden.io/providers/conftest-kubernetes) providers. See the [conftest example project](/~https://github.com/garden-io/garden/tree/master/examples/conftest) for a simple usage example of the latter. +Note that, in many cases, you'll actually want to use more specific providers that can automatically configure your `conftest` modules, e.g. the [`conftest-container`](https://docs.garden.io/reference/module-types/conftest-container) and/or [`conftest-kubernetes`](https://docs.garden.io/reference/module-types/conftest-kubernetes) providers. See the [conftest example project](/~https://github.com/garden-io/garden/tree/master/examples/conftest) for a simple usage example of the latter. -If those don't match your needs, you can use this provider directly and manually configure your `conftest` modules. Simply add this provider to your project configuration, and see the [conftest module documentation](https://docs.garden.io/module-types/conftest) for a detailed reference. Also, check out the below reference for how to configure default policies, default namespaces, and test failure thresholds for all `conftest` modules. +If those don't match your needs, you can use this provider directly and manually configure your `conftest` modules. Simply add this provider to your project configuration, and see the [conftest module documentation](https://docs.garden.io/reference/module-types/conftest) for a detailed reference. Also, check out the below reference for how to configure default policies, default namespaces, and test failure thresholds for all `conftest` modules. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/hadolint.md b/docs/reference/providers/hadolint.md similarity index 75% rename from docs/providers/hadolint.md rename to docs/reference/providers/hadolint.md index 50f853282f5..9b5eeb675a2 100644 --- a/docs/providers/hadolint.md +++ b/docs/reference/providers/hadolint.md @@ -7,19 +7,13 @@ tocTitle: "`hadolint`" ## Description -This provider creates a [`hadolint`](https://docs.garden.io/module-types/hadolint) module type, and (by default) generates one -such module for each `container` module that contains a Dockerfile in your project. Each module creates a single -test that runs [hadolint](/~https://github.com/hadolint/hadolint) against the Dockerfile in question, in order to -ensure that the Dockerfile is valid and follows best practices. +This provider creates a [`hadolint`](https://docs.garden.io/reference/module-types/hadolint) module type, and (by default) generates one such module for each `container` module that contains a Dockerfile in your project. Each module creates a single test that runs [hadolint](/~https://github.com/hadolint/hadolint) against the Dockerfile in question, in order to ensure that the Dockerfile is valid and follows best practices. -To configure `hadolint`, you can use `.hadolint.yaml` config files. For each test, we first look for one in -the relevant module root. If none is found there, we check the project root, and if none is there we fall back to -default configuration. Note that for reasons of portability, we do not fall back to global/user configuration files. +To configure `hadolint`, you can use `.hadolint.yaml` config files. For each test, we first look for one in the relevant module root. If none is found there, we check the project root, and if none is there we fall back to default configuration. Note that for reasons of portability, we do not fall back to global/user configuration files. -See the [hadolint docs](/~https://github.com/hadolint/hadolint#configure) for details on how to configure it, and the -[hadolint example project](/~https://github.com/garden-io/garden/tree/master/examples/hadolint) for a usage example. +See the [hadolint docs](/~https://github.com/hadolint/hadolint#configure) for details on how to configure it, and the [hadolint example project](/~https://github.com/garden-io/garden/tree/master/examples/hadolint) for a usage example. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/kubernetes.md b/docs/reference/providers/kubernetes.md similarity index 99% rename from docs/providers/kubernetes.md rename to docs/reference/providers/kubernetes.md index 6b98e81b7ae..485cfe2805c 100644 --- a/docs/providers/kubernetes.md +++ b/docs/reference/providers/kubernetes.md @@ -7,19 +7,17 @@ tocTitle: "`kubernetes`" ## Description -The `kubernetes` provider allows you to deploy [`container` modules](https://docs.garden.io/module-types/container) to -Kubernetes clusters, and adds the [`helm`](https://docs.garden.io/module-types/helm) and -[`kubernetes`](https://docs.garden.io/module-types/kubernetes) module types. +The `kubernetes` provider allows you to deploy [`container` modules](https://docs.garden.io/reference/module-types/container) to +Kubernetes clusters, and adds the [`helm`](https://docs.garden.io/reference/module-types/helm) and +[`kubernetes`](https://docs.garden.io/reference/module-types/kubernetes) module types. For usage information, please refer to the [guides section]https://docs.garden.io/guides). A good place to start is the [Remote Kubernetes guide](https://docs.garden.io/guides/remote-kubernetes) guide if you're connecting to remote clusters. The [demo-project](https://docs.garden.io/examples/demo-project) example project and guide are also helpful as an introduction. -Note that if you're using a local Kubernetes cluster (e.g. minikube or Docker Desktop), the -[local-kubernetes provider](https://docs.garden.io/providers/local-kubernetes) simplifies (and automates) the configuration and setup quite a -bit. +Note that if you're using a local Kubernetes cluster (e.g. minikube or Docker Desktop), the [local-kubernetes provider](https://docs.garden.io/reference/providers/local-kubernetes) simplifies (and automates) the configuration and setup quite a bit. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/local-kubernetes.md b/docs/reference/providers/local-kubernetes.md similarity index 98% rename from docs/providers/local-kubernetes.md rename to docs/reference/providers/local-kubernetes.md index 4e23d7852f1..bb14f7ec87a 100644 --- a/docs/providers/local-kubernetes.md +++ b/docs/reference/providers/local-kubernetes.md @@ -7,17 +7,13 @@ tocTitle: "`local-kubernetes`" ## Description -The `local-kubernetes` provider is a specialized version of the [`kubernetes` provider](https://docs.garden.io/providers/kubernetes) that -automates and simplifies working with local Kubernetes clusters. +The `local-kubernetes` provider is a specialized version of the [`kubernetes` provider](https://docs.garden.io/reference/providers/kubernetes) that automates and simplifies working with local Kubernetes clusters. -For general Kubernetes usage information, please refer to the [guides section](https://docs.garden.io/guides). For local -clusters a good place to start is the [Local Kubernetes guide](https://docs.garden.io/guides/local-kubernetes) guide. -The [demo-project](https://docs.garden.io/examples/demo-project) example project and guide are also helpful as an introduction. +For general Kubernetes usage information, please refer to the [guides section](https://docs.garden.io/guides). For local clusters a good place to start is the [Local Kubernetes guide](https://docs.garden.io/guides/local-kubernetes) guide. The [demo-project](https://docs.garden.io/examples/demo-project) example project and guide are also helpful as an introduction. -If you're working with a remote Kubernetes cluster, please refer to the [`kubernetes` provider](https://docs.garden.io/providers/kubernetes) -docs, and the [Remote Kubernetes guide](https://docs.garden.io/guides/remote-kubernetes) guide. +If you're working with a remote Kubernetes cluster, please refer to the [`kubernetes` provider](https://docs.garden.io/reference/providers/kubernetes) docs, and the [Remote Kubernetes guide](https://docs.garden.io/guides/remote-kubernetes) guide. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/maven-container.md b/docs/reference/providers/maven-container.md similarity index 78% rename from docs/providers/maven-container.md rename to docs/reference/providers/maven-container.md index 464c47b2e20..4532b046339 100644 --- a/docs/providers/maven-container.md +++ b/docs/reference/providers/maven-container.md @@ -7,13 +7,11 @@ tocTitle: "`maven-container`" ## Description -Adds the [maven-container module type](https://docs.garden.io/module-types/maven-container), which is a specialized version of the -`container` module type that has special semantics for building JAR files using Maven. +Adds the [maven-container module type](https://docs.garden.io/reference/module-types/maven-container), which is a specialized version of the `container` module type that has special semantics for building JAR files using Maven. -To use it, simply add the provider to your provider configuration, and refer to the -[maven-container module docs](https://docs.garden.io/module-types/maven-container) for details on how to configure the modules. +To use it, simply add the provider to your provider configuration, and refer to the [maven-container module docs](https://docs.garden.io/reference/module-types/maven-container) for details on how to configure the modules. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/openfaas.md b/docs/reference/providers/openfaas.md similarity index 93% rename from docs/providers/openfaas.md rename to docs/reference/providers/openfaas.md index 77e060ba1b2..ef45f4418fb 100644 --- a/docs/providers/openfaas.md +++ b/docs/reference/providers/openfaas.md @@ -7,13 +7,13 @@ tocTitle: "`openfaas`" ## Description -This provider adds support for [OpenFaaS](https://www.openfaas.com/). It adds the [`openfaas` module type](https://docs.garden.io/module-types/openfaas) and (by default) installs the `faas-netes` runtime to the project namespace. Each `openfaas` module maps to a single OpenFaaS function. +This provider adds support for [OpenFaaS](https://www.openfaas.com/). It adds the [`openfaas` module type](https://docs.garden.io/reference/module-types/openfaas) and (by default) installs the `faas-netes` runtime to the project namespace. Each `openfaas` module maps to a single OpenFaaS function. -See the reference below for configuration options for `faas-netes`, and the [module type docs](https://docs.garden.io/module-types/openfaas) for how to configure the individual functions. +See the reference below for configuration options for `faas-netes`, and the [module type docs](https://docs.garden.io/reference/module-types/openfaas) for how to configure the individual functions. Also see the [openfaas example project](/~https://github.com/garden-io/garden/tree/master/examples/openfaas) for a simple usage example. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/providers/terraform.md b/docs/reference/providers/terraform.md similarity index 97% rename from docs/providers/terraform.md rename to docs/reference/providers/terraform.md index 632218d296b..41b8a2ca3c2 100644 --- a/docs/providers/terraform.md +++ b/docs/reference/providers/terraform.md @@ -10,7 +10,7 @@ tocTitle: "`terraform`" This provider allows you to integrate Terraform stacks into your Garden project. See the [Terraform guide](https://docs.garden.io/guides/terraform) for details and usage information. -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/docs/reference/template-strings.md b/docs/reference/template-strings.md index 48a20e3e1e0..f3d9b0fae42 100644 --- a/docs/reference/template-strings.md +++ b/docs/reference/template-strings.md @@ -1,5 +1,6 @@ --- -title: Template Strings Reference +order: 5 +title: Template Strings --- # Template string reference diff --git a/docs/using-garden/adding-modules.md b/docs/using-garden/adding-modules.md index d40d5493793..572b5a834c2 100644 --- a/docs/using-garden/adding-modules.md +++ b/docs/using-garden/adding-modules.md @@ -60,7 +60,7 @@ Modules correspond to a **build** action in the Stack Graph. ## Examples -You can learn more about different module types in the [module type reference docs](../module-types/README.md). +You can learn more about different module types in the [module type reference docs](../reference/module-types/README.md). ### Container Module @@ -125,7 +125,7 @@ Note however, that if a disabled module is referenced as a build dependency of a ## Further Reading -* [Module type reference docs](../module-types/README.md). +* [Module type reference docs](../reference/module-types/README.md). * [Multiple modules in the same configuration file](../guides/configuration-files.md#multiple-modules-in-the-same-file). * [A guide on the container module type](../guides/container-modules.md). diff --git a/docs/using-garden/adding-services.md b/docs/using-garden/adding-services.md index 14ac39d2eda..25b727dc96f 100644 --- a/docs/using-garden/adding-services.md +++ b/docs/using-garden/adding-services.md @@ -17,7 +17,7 @@ services: containerPort: 8080 ``` -> Note that not all [modules types](../module-types/README.md) have services. +> Note that not all [modules types](../reference/module-types/README.md) have services. ## How it Works @@ -122,7 +122,7 @@ By default the Kubernetes provider does a rolling update for deployments. ## Further Reading -* For full service configuration by module type, please take a look at our [reference docs](../module-types/README.md). +* For full service configuration by module type, please take a look at our [reference docs](../reference/module-types/README.md). ## Next Steps diff --git a/docs/using-garden/creating-a-project.md b/docs/using-garden/creating-a-project.md index 9d2e657728f..e22e6ba7ff1 100644 --- a/docs/using-garden/creating-a-project.md +++ b/docs/using-garden/creating-a-project.md @@ -63,7 +63,7 @@ Our choice of providers and their configuration dictates how the module in the e Some of the most commonly used providers are the [local Kubernetes provider](../guides/local-kubernetes.md) and the [remote Kubernetes provider](../guides/remote-kubernetes.md). -Here's the [full list of supported providers](../providers/README.md). +Here's the [full list of supported providers](../reference/providers/README.md). ## Examples diff --git a/docs/using-garden/running-tasks.md b/docs/using-garden/running-tasks.md index 5115a3b8417..7e0c1a31bf3 100644 --- a/docs/using-garden/running-tasks.md +++ b/docs/using-garden/running-tasks.md @@ -15,7 +15,7 @@ You add tasks when you want Garden to execute specific commands before deploying - name: db-clear args: [rake, db:rollback] -> Note that not all [modules types](../module-types/README.md) support tasks. +> Note that not all [modules types](../reference/module-types/README.md) support tasks. ## How it Works @@ -109,7 +109,7 @@ tasks: After running `my-task`, you can find the contents of the `report` directory in the task's container, locally under `.garden/artifacts/my-task-report`. -Please look at individual [module type references](../module-types/README.md) to see how to configure each module type's tasks to extract artifacts after running them. +Please look at individual [module type references](../reference/module-types/README.md) to see how to configure each module type's tasks to extract artifacts after running them. ### Disabling Tasks @@ -146,7 +146,7 @@ source directory instead. ## Further Reading -* For full task configuration by module type, please take a look at our [reference docs](../module-types/README.md). +* For full task configuration by module type, please take a look at our [reference docs](../reference/module-types/README.md). ## Next Steps diff --git a/docs/using-garden/running-tests.md b/docs/using-garden/running-tests.md index bfa5b9bea1f..d9ad980799c 100644 --- a/docs/using-garden/running-tests.md +++ b/docs/using-garden/running-tests.md @@ -19,7 +19,7 @@ tests: - backend ``` -> Note that not all [modules types](../module-types/README.md) support tests. +> Note that not all [modules types](../reference/module-types/README.md) support tests. ## How it Works @@ -45,7 +45,7 @@ Tests correspond to a **test** action in the Stack Graph. ## Examples -For full test configuration by module type, please take a look at our [reference docs](../module-types/README.md). +For full test configuration by module type, please take a look at our [reference docs](../reference/module-types/README.md). ### Integration Testing @@ -107,7 +107,7 @@ tests: After running `my-test`, you can find the contents of the `report` directory in the test's container, locally under `.garden/artifacts/my-test-report`. -Please look at individual [module type references](../module-types/README.md) to see how to configure each module type's tests to extract artifacts after running them. +Please look at individual [module type references](../reference/module-types/README.md) to see how to configure each module type's tests to extract artifacts after running them. ### Disabling Tests diff --git a/garden-service/src/commands/create/create-module.ts b/garden-service/src/commands/create/create-module.ts index bc1711ba3e2..b7260c14fac 100644 --- a/garden-service/src/commands/create/create-module.ts +++ b/garden-service/src/commands/create/create-module.ts @@ -38,6 +38,7 @@ import { LoggerType } from "../../logger/logger" import Bluebird from "bluebird" import { ModuleTypeMap } from "../../types/plugin/plugin" import { LogEntry } from "../../logger/log-entry" +import { getProviderUrl, getModuleTypeUrl } from "../../docs/common" const createModuleArgs = {} const createModuleOpts = { @@ -251,8 +252,8 @@ export class CreateModuleCommand extends Command) { const path = tree.path.replace(docsRoot, ".") - let output = repeat(indent, depth) + "* [" + tree.title + "](" + path + ")\n" + let output: string + + if (depth === 0) { + const emoji = emojis.values().next().value + output = `\n## ${emoji} ${tree.title}\n\n` + emojis.delete(emoji) + } else { + output = repeat(indent, depth - 1) + `* [${tree.title}](${path})\n` + } + // We don't want the root directory of the docs to be a TOC item. if (tree.topLevel) { output = "" @@ -135,7 +147,7 @@ function generateMarkdown(tree: FileTree, docsRoot: string, depth = 0) { output = "" } for (let item in tree.children) { - output += generateMarkdown(tree.children[item], docsRoot, depth + 1) + output += generateMarkdown(tree.children[item], docsRoot, depth + 1, emojis) } return output } @@ -150,7 +162,7 @@ export function generateTableOfContents(docsRoot: string): string { rawTree.topLevel = true const treeWithMetadata = createNewTree(rawTree, attachMetadata) const preparedTree = createNewTree(treeWithMetadata, sortTree) - return "# Table of Contents\n\n" + generateMarkdown(preparedTree, docsRoot) + return "# Table of Contents\n" + generateMarkdown(preparedTree, docsRoot, 0, new Set(emojiList)) } export async function writeTableOfContents(docsRoot: string, outputFileName: string) { diff --git a/garden-service/src/docs/templates/base-config.hbs b/garden-service/src/docs/templates/base-config.hbs index ec0722941e0..6c12265dee2 100644 --- a/garden-service/src/docs/templates/base-config.hbs +++ b/garden-service/src/docs/templates/base-config.hbs @@ -1,6 +1,6 @@ --- -order: 3 -title: Config Files Reference +order: 4 +title: Config Files --- # garden.yml reference @@ -12,9 +12,9 @@ The reference is divided into four sections. The [first section](#project-yaml-s The [third section](#module-yaml-schema) contains the module level YAML schema, and the [fourth section](#module-configuration-keys) describes each individual schema key for the module level configuration. -Note that individual providers, e.g. `kubernetes`, add their own project level configuration keys. The provider types are listed on the [Providers page](../providers/README.md). +Note that individual providers, e.g. `kubernetes`, add their own project level configuration keys. The provider types are listed on the [Providers page](../reference/providers/README.md). -Likewise, individual module types, e.g. `container`, add additional configuration keys at the module level. Module types are listed on the [Module Types page](../module-types/README.md). +Likewise, individual module types, e.g. `container`, add additional configuration keys at the module level. Module types are listed on the [Module Types page](../reference/module-types/README.md). Please refer to those for more details on provider and module configuration. diff --git a/garden-service/src/docs/templates/commands.hbs b/garden-service/src/docs/templates/commands.hbs index 51bebdc7f04..01a7e34abac 100644 --- a/garden-service/src/docs/templates/commands.hbs +++ b/garden-service/src/docs/templates/commands.hbs @@ -1,6 +1,6 @@ --- -order: 2 -title: Commands Reference +order: 3 +title: Commands --- ## Garden CLI commands diff --git a/garden-service/src/docs/templates/module-type.hbs b/garden-service/src/docs/templates/module-type.hbs index e018d40eb2c..bcc445c3098 100644 --- a/garden-service/src/docs/templates/module-type.hbs +++ b/garden-service/src/docs/templates/module-type.hbs @@ -10,7 +10,7 @@ tocTitle: "`{{{name}}}`" {{{docs}}} Below is the full schema reference. For an introduction to configuring Garden modules, please look at our [Configuration -guide](../guides/configuration-files.md). +guide](../../guides/configuration-files.md). The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/garden-service/src/docs/templates/provider.hbs b/garden-service/src/docs/templates/provider.hbs index 46f0a2cfc3d..904d8c543c2 100644 --- a/garden-service/src/docs/templates/provider.hbs +++ b/garden-service/src/docs/templates/provider.hbs @@ -9,7 +9,7 @@ tocTitle: "`{{{name}}}`" {{{docs}}} -Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../guides/configuration-files.md). +Below is the full schema reference for the provider configuration. For an introduction to configuring a Garden project with providers, please look at our [configuration guide](../../guides/configuration-files.md). The reference is divided into two sections. The [first section](#complete-yaml-schema) contains the complete YAML schema, and the [second section](#configuration-keys) describes each schema key. diff --git a/garden-service/src/docs/templates/template-strings.hbs b/garden-service/src/docs/templates/template-strings.hbs index 5024a6ec68e..fb9e677bce2 100644 --- a/garden-service/src/docs/templates/template-strings.hbs +++ b/garden-service/src/docs/templates/template-strings.hbs @@ -1,5 +1,6 @@ --- -title: Template Strings Reference +order: 5 +title: Template Strings --- # Template string reference diff --git a/garden-service/src/plugins/conftest/conftest-container.ts b/garden-service/src/plugins/conftest/conftest-container.ts index 01e596f8047..6bfc52bea1b 100644 --- a/garden-service/src/plugins/conftest/conftest-container.ts +++ b/garden-service/src/plugins/conftest/conftest-container.ts @@ -12,7 +12,9 @@ import { createGardenPlugin } from "../../types/plugin/plugin" import { containerHelpers } from "../container/helpers" import { ConftestProvider } from "./conftest" import { dedent } from "../../util/string" -import { DOCS_BASE_URL } from "../../constants" +import { getModuleTypeUrl } from "../../docs/common" + +const moduleTypeUrl = getModuleTypeUrl("conftest") /** * Auto-generates a conftest module for each container module in your project @@ -22,13 +24,9 @@ export const gardenPlugin = createGardenPlugin({ base: "conftest", dependencies: ["container"], docs: dedent` - This provider automatically generates [conftest modules](${DOCS_BASE_URL}/module-types/conftest) for \`container\` modules - in your project. A \`conftest\` module is created for each \`container\` module that includes a Dockerfile that - can be validated. + This provider automatically generates [conftest modules](${moduleTypeUrl}) for \`container\` modules in your project. A \`conftest\` module is created for each \`container\` module that includes a Dockerfile that can be validated. - Simply add this provider to your project configuration, and configure your policies. Check out the below - reference for how to configure default policies, default namespaces, and test failure thresholds for the generated - modules. + Simply add this provider to your project configuration, and configure your policies. Check out the below reference for how to configure default policies, default namespaces, and test failure thresholds for the generated modules. `, handlers: { augmentGraph: async ({ ctx, modules }) => { diff --git a/garden-service/src/plugins/conftest/conftest-kubernetes.ts b/garden-service/src/plugins/conftest/conftest-kubernetes.ts index 36a2218244f..f9024cdd44c 100644 --- a/garden-service/src/plugins/conftest/conftest-kubernetes.ts +++ b/garden-service/src/plugins/conftest/conftest-kubernetes.ts @@ -11,7 +11,9 @@ import { createGardenPlugin } from "../../types/plugin/plugin" import { ConftestProvider } from "./conftest" import { relative, resolve } from "path" import { dedent } from "../../util/string" -import { DOCS_BASE_URL } from "../../constants" +import { getModuleTypeUrl } from "../../docs/common" + +const moduleTypeUrl = getModuleTypeUrl("conftest") /** * Auto-generates a conftest module for each helm and kubernetes module in your project @@ -21,7 +23,7 @@ export const gardenPlugin = createGardenPlugin({ base: "conftest", dependencies: ["kubernetes"], docs: dedent` - This provider automatically generates [conftest modules](${DOCS_BASE_URL}/module-types/conftest) for \`kubernetes\` and + This provider automatically generates [conftest modules](${moduleTypeUrl}) for \`kubernetes\` and \`helm\` modules in your project. A \`conftest\` module is created for each of those module types. Simply add this provider to your project configuration, and configure your policies. Check out the below diff --git a/garden-service/src/plugins/conftest/conftest.ts b/garden-service/src/plugins/conftest/conftest.ts index 24f8d41680b..158a53e88f1 100644 --- a/garden-service/src/plugins/conftest/conftest.ts +++ b/garden-service/src/plugins/conftest/conftest.ts @@ -18,7 +18,7 @@ import chalk from "chalk" import { baseBuildSpecSchema } from "../../config/module" import { matchGlobs, listDirectory } from "../../util/fs" import { PluginError } from "../../exceptions" -import { DOCS_BASE_URL } from "../../constants" +import { getModuleTypeUrl } from "../../docs/common" interface ConftestProviderConfig extends ProviderConfig { policyPath: string @@ -59,14 +59,18 @@ interface ConftestModuleSpec { type ConftestModule = Module +const moduleTypeUrl = getModuleTypeUrl("conftest") +const containerModuleTypeUrl = getModuleTypeUrl("conftest-container") +const kubernetesModuleTypeUrl = getModuleTypeUrl("conftest-kubernetes") + export const gardenPlugin = createGardenPlugin({ name: "conftest", docs: dedent` This provider allows you to validate your configuration files against policies that you specify, using the [conftest tool](/~https://github.com/instrumenta/conftest) and Open Policy Agent rego query files. The provider creates a module type of the same name, which allows you to specify files to validate. Each module then creates a Garden test that becomes part of your Stack Graph. - Note that, in many cases, you'll actually want to use more specific providers that can automatically configure your \`conftest\` modules, e.g. the [\`conftest-container\`](${DOCS_BASE_URL}/providers/conftest-container) and/or [\`conftest-kubernetes\`](${DOCS_BASE_URL}/providers/conftest-kubernetes) providers. See the [conftest example project](/~https://github.com/garden-io/garden/tree/master/examples/conftest) for a simple usage example of the latter. + Note that, in many cases, you'll actually want to use more specific providers that can automatically configure your \`conftest\` modules, e.g. the [\`conftest-container\`](${containerModuleTypeUrl}) and/or [\`conftest-kubernetes\`](${kubernetesModuleTypeUrl}) providers. See the [conftest example project](/~https://github.com/garden-io/garden/tree/master/examples/conftest) for a simple usage example of the latter. - If those don't match your needs, you can use this provider directly and manually configure your \`conftest\` modules. Simply add this provider to your project configuration, and see the [conftest module documentation](${DOCS_BASE_URL}/module-types/conftest) for a detailed reference. Also, check out the below reference for how to configure default policies, default namespaces, and test failure thresholds for all \`conftest\` modules. + If those don't match your needs, you can use this provider directly and manually configure your \`conftest\` modules. Simply add this provider to your project configuration, and see the [conftest module documentation](${moduleTypeUrl}) for a detailed reference. Also, check out the below reference for how to configure default policies, default namespaces, and test failure thresholds for all \`conftest\` modules. `, dependencies: [], configSchema, @@ -77,7 +81,7 @@ export const gardenPlugin = createGardenPlugin({ Creates a test that runs \`conftest\` on the specified files, with the specified (or default) policy and namespace. - > Note: In many cases, you'll let specific conftest providers (e.g. [\`conftest-container\`](${DOCS_BASE_URL}/providers/conftest-container) and [\`conftest-kubernetes\`](${DOCS_BASE_URL}/providers/conftest-kubernetes) create this module type automatically, but you may in some cases want or need to manually specify files to test. + > Note: In many cases, you'll let specific conftest providers (e.g. [\`conftest-container\`](${containerModuleTypeUrl}) and [\`conftest-kubernetes\`](${kubernetesModuleTypeUrl}) create this module type automatically, but you may in some cases want or need to manually specify files to test. See the [conftest docs](/~https://github.com/instrumenta/conftest) for details on how to configure policies. `, diff --git a/garden-service/src/plugins/container/config.ts b/garden-service/src/plugins/container/config.ts index 3c7fdfa33f9..497aed6a0d1 100644 --- a/garden-service/src/plugins/container/config.ts +++ b/garden-service/src/plugins/container/config.ts @@ -22,13 +22,14 @@ import { } from "../../config/common" import { ArtifactSpec } from "./../../config/validation" import { Service, ingressHostnameSchema, linkUrlSchema } from "../../types/service" -import { DEFAULT_PORT_PROTOCOL, DOCS_BASE_URL } from "../../constants" +import { DEFAULT_PORT_PROTOCOL } from "../../constants" import { ModuleSpec, ModuleConfig, baseBuildSpecSchema, BaseBuildSpec } from "../../config/module" import { CommonServiceSpec, ServiceConfig, baseServiceSpecSchema } from "../../config/service" import { baseTaskSpecSchema, BaseTaskSpec, cacheResultSchema } from "../../config/task" import { baseTestSpecSchema, BaseTestSpec } from "../../config/test" import { joiStringMap } from "../../config/common" import { dedent } from "../../util/string" +import { getModuleTypeUrl } from "../../docs/common" export const defaultContainerLimits: ServiceLimitSpec = { cpu: 1000, // = 1000 millicpu = 1 CPU @@ -318,6 +319,8 @@ export const portSchema = () => `), }) +const moduleTypeUrl = getModuleTypeUrl("persistentvolumeclaim") + const volumeSchema = () => joi .object() @@ -343,7 +346,7 @@ const volumeSchema = () => .example("/some/dir"), module: joiIdentifier().description( dedent` - The name of a _volume module_ that should be mounted at \`containerPath\`. The supported module types will depend on which provider you are using. The \`kubernetes\` provider supports the [persistentvolumeclaim module](${DOCS_BASE_URL}/module-types/persistentvolumeclaim), for example. + The name of a _volume module_ that should be mounted at \`containerPath\`. The supported module types will depend on which provider you are using. The \`kubernetes\` provider supports the [persistentvolumeclaim module](${moduleTypeUrl}), for example. When a \`module\` is specified, the referenced module/volume will be automatically configured as a runtime dependency of this service, as well as a build dependency of this module. diff --git a/garden-service/src/plugins/container/container.ts b/garden-service/src/plugins/container/container.ts index 9f9e7fc290c..dcf511d4a79 100644 --- a/garden-service/src/plugins/container/container.ts +++ b/garden-service/src/plugins/container/container.ts @@ -19,10 +19,10 @@ import { ConfigureModuleParams } from "../../types/plugin/module/configure" import { HotReloadServiceParams } from "../../types/plugin/service/hotReloadService" import { joi } from "../../config/common" import { publishContainerModule } from "./publish" -import { DOCS_BASE_URL } from "../../constants" import { SuggestModulesParams, SuggestModulesResult } from "../../types/plugin/module/suggestModules" import { listDirectory } from "../../util/fs" import { dedent } from "../../util/string" +import { getModuleTypeUrl } from "../../docs/common" export const containerModuleOutputsSchema = () => joi.object().keys({ @@ -223,8 +223,8 @@ export const gardenPlugin = createGardenPlugin({ Note that the runtime services have somewhat limited features in this module type. For example, you cannot specify replicas for redundancy, and various platform-specific options are not included. For those, look at - other module types like [helm](${DOCS_BASE_URL}/module-types/helm) or - [kubernetes](${DOCS_BASE_URL}/module-types/kubernetes). + other module types like [helm](${getModuleTypeUrl("helm")}) or + [kubernetes](${getModuleTypeUrl("kubernetes")}). `, moduleOutputsSchema: containerModuleOutputsSchema(), schema: containerModuleSpecSchema(), diff --git a/garden-service/src/plugins/hadolint/hadolint.ts b/garden-service/src/plugins/hadolint/hadolint.ts index 9f66a2e9c51..6ceb4c2604f 100644 --- a/garden-service/src/plugins/hadolint/hadolint.ts +++ b/garden-service/src/plugins/hadolint/hadolint.ts @@ -16,12 +16,13 @@ import { dedent, splitLines, naturalList } from "../../util/string" import { TestModuleParams } from "../../types/plugin/module/testModule" import { Module } from "../../types/module" import { BinaryCmd } from "../../util/ext-tools" -import { STATIC_DIR, DOCS_BASE_URL } from "../../constants" +import { STATIC_DIR } from "../../constants" import { padStart, padEnd } from "lodash" import chalk from "chalk" import { ConfigurationError } from "../../exceptions" import { containerHelpers } from "../container/helpers" import { baseBuildSpecSchema } from "../../config/module" +import { getProviderUrl, getModuleTypeUrl } from "../../docs/common" const defaultConfigPath = join(STATIC_DIR, "hadolint", "default.hadolint.yaml") const configFilename = ".hadolint.yaml" @@ -63,21 +64,18 @@ interface HadolintModuleSpec { type HadolintModule = Module +const moduleTypeUrl = getModuleTypeUrl("hadolint") +const providerUrl = getProviderUrl("hadolint") + export const gardenPlugin = createGardenPlugin({ name: "hadolint", dependencies: ["container"], docs: dedent` - This provider creates a [\`hadolint\`](${DOCS_BASE_URL}/module-types/hadolint) module type, and (by default) generates one - such module for each \`container\` module that contains a Dockerfile in your project. Each module creates a single - test that runs [hadolint](/~https://github.com/hadolint/hadolint) against the Dockerfile in question, in order to - ensure that the Dockerfile is valid and follows best practices. + This provider creates a [\`hadolint\`](${moduleTypeUrl}) module type, and (by default) generates one such module for each \`container\` module that contains a Dockerfile in your project. Each module creates a single test that runs [hadolint](/~https://github.com/hadolint/hadolint) against the Dockerfile in question, in order to ensure that the Dockerfile is valid and follows best practices. - To configure \`hadolint\`, you can use \`.hadolint.yaml\` config files. For each test, we first look for one in - the relevant module root. If none is found there, we check the project root, and if none is there we fall back to - default configuration. Note that for reasons of portability, we do not fall back to global/user configuration files. + To configure \`hadolint\`, you can use \`.hadolint.yaml\` config files. For each test, we first look for one in the relevant module root. If none is found there, we check the project root, and if none is there we fall back to default configuration. Note that for reasons of portability, we do not fall back to global/user configuration files. - See the [hadolint docs](/~https://github.com/hadolint/hadolint#configure) for details on how to configure it, and the - [hadolint example project](/~https://github.com/garden-io/garden/tree/master/examples/hadolint) for a usage example. + See the [hadolint docs](/~https://github.com/hadolint/hadolint#configure) for details on how to configure it, and the [hadolint example project](/~https://github.com/garden-io/garden/tree/master/examples/hadolint) for a usage example. `, configSchema, handlers: { @@ -136,7 +134,7 @@ export const gardenPlugin = createGardenPlugin({ docs: dedent` Runs \`hadolint\` on the specified Dockerfile. - > Note: In most cases, you'll let the [provider](${DOCS_BASE_URL}/providers/hadolint) create this module type automatically, but you may in some cases want or need to manually specify a Dockerfile to lint. + > Note: In most cases, you'll let the [provider](${providerUrl}) create this module type automatically, but you may in some cases want or need to manually specify a Dockerfile to lint. To configure \`hadolint\`, you can use \`.hadolint.yaml\` config files. For each test, we first look for one in the module root. If none is found there, we check the project root, and if none is there we fall back to default diff --git a/garden-service/src/plugins/kubernetes/kubernetes.ts b/garden-service/src/plugins/kubernetes/kubernetes.ts index b6031cb1b9d..16470c4e1b1 100644 --- a/garden-service/src/plugins/kubernetes/kubernetes.ts +++ b/garden-service/src/plugins/kubernetes/kubernetes.ts @@ -37,6 +37,7 @@ import { removeTillerCmd } from "./commands/remove-tiller" import { DOCS_BASE_URL } from "../../constants" import { inClusterRegistryHostname } from "./constants" import { pvcModuleDefinition } from "./volumes/persistentvolumeclaim" +import { getModuleTypeUrl, getProviderUrl } from "../../docs/common" export async function configureProvider({ projectName, @@ -168,21 +169,21 @@ const outputsSchema = joi.object().keys({ .description("The namespace used for Garden metadata."), }) +const localKubernetesUrl = getProviderUrl("local-kubernetes") + export const gardenPlugin = createGardenPlugin({ name: "kubernetes", dependencies: ["container"], docs: dedent` - The \`kubernetes\` provider allows you to deploy [\`container\` modules](${DOCS_BASE_URL}/module-types/container) to - Kubernetes clusters, and adds the [\`helm\`](${DOCS_BASE_URL}/module-types/helm) and - [\`kubernetes\`](${DOCS_BASE_URL}/module-types/kubernetes) module types. + The \`kubernetes\` provider allows you to deploy [\`container\` modules](${getModuleTypeUrl("container")}) to + Kubernetes clusters, and adds the [\`helm\`](${getModuleTypeUrl("helm")}) and + [\`kubernetes\`](${getModuleTypeUrl("kubernetes")}) module types. For usage information, please refer to the [guides section]${DOCS_BASE_URL}/guides). A good place to start is the [Remote Kubernetes guide](${DOCS_BASE_URL}/guides/remote-kubernetes) guide if you're connecting to remote clusters. The [demo-project](${DOCS_BASE_URL}/examples/demo-project) example project and guide are also helpful as an introduction. - Note that if you're using a local Kubernetes cluster (e.g. minikube or Docker Desktop), the - [local-kubernetes provider](${DOCS_BASE_URL}/providers/local-kubernetes) simplifies (and automates) the configuration and setup quite a - bit. + Note that if you're using a local Kubernetes cluster (e.g. minikube or Docker Desktop), the [local-kubernetes provider](${localKubernetesUrl}) simplifies (and automates) the configuration and setup quite a bit. `, configSchema, outputsSchema, @@ -219,8 +220,7 @@ export const gardenPlugin = createGardenPlugin({ Note that if you include the manifests in the \`garden.yml\` file, you can use [template strings](${DOCS_BASE_URL}/guides/variables-and-templating) to interpolate values into the manifests. - If you need more advanced templating features you can use the - [helm](${DOCS_BASE_URL}/module-types/helm) module type. + If you need more advanced templating features you can use the [helm](${getModuleTypeUrl("helm")}) module type. `, moduleOutputsSchema: joi.object().keys({}), schema: kubernetesModuleSpecSchema(), diff --git a/garden-service/src/plugins/kubernetes/local/local.ts b/garden-service/src/plugins/kubernetes/local/local.ts index be2b6682026..c55b6895911 100644 --- a/garden-service/src/plugins/kubernetes/local/local.ts +++ b/garden-service/src/plugins/kubernetes/local/local.ts @@ -10,20 +10,19 @@ import { configureProvider, configSchema } from "./config" import { createGardenPlugin } from "../../../types/plugin/plugin" import { dedent } from "../../../util/string" import { DOCS_BASE_URL } from "../../../constants" +import { getProviderUrl } from "../../../docs/common" + +const providerUrl = getProviderUrl("kubernetes") export const gardenPlugin = createGardenPlugin({ name: "local-kubernetes", base: "kubernetes", docs: dedent` - The \`local-kubernetes\` provider is a specialized version of the [\`kubernetes\` provider](${DOCS_BASE_URL}/providers/kubernetes) that - automates and simplifies working with local Kubernetes clusters. + The \`local-kubernetes\` provider is a specialized version of the [\`kubernetes\` provider](${providerUrl}) that automates and simplifies working with local Kubernetes clusters. - For general Kubernetes usage information, please refer to the [guides section](${DOCS_BASE_URL}/guides). For local - clusters a good place to start is the [Local Kubernetes guide](${DOCS_BASE_URL}/guides/local-kubernetes) guide. - The [demo-project](${DOCS_BASE_URL}/examples/demo-project) example project and guide are also helpful as an introduction. + For general Kubernetes usage information, please refer to the [guides section](${DOCS_BASE_URL}/guides). For local clusters a good place to start is the [Local Kubernetes guide](${DOCS_BASE_URL}/guides/local-kubernetes) guide. The [demo-project](${DOCS_BASE_URL}/examples/demo-project) example project and guide are also helpful as an introduction. - If you're working with a remote Kubernetes cluster, please refer to the [\`kubernetes\` provider](${DOCS_BASE_URL}/providers/kubernetes) - docs, and the [Remote Kubernetes guide](${DOCS_BASE_URL}/guides/remote-kubernetes) guide. + If you're working with a remote Kubernetes cluster, please refer to the [\`kubernetes\` provider](${providerUrl}) docs, and the [Remote Kubernetes guide](${DOCS_BASE_URL}/guides/remote-kubernetes) guide. `, configSchema, handlers: { diff --git a/garden-service/src/plugins/kubernetes/volumes/persistentvolumeclaim.ts b/garden-service/src/plugins/kubernetes/volumes/persistentvolumeclaim.ts index d73c3eeaefc..832330b3fa9 100644 --- a/garden-service/src/plugins/kubernetes/volumes/persistentvolumeclaim.ts +++ b/garden-service/src/plugins/kubernetes/volumes/persistentvolumeclaim.ts @@ -22,6 +22,7 @@ import { KubernetesModule, KubernetesModuleConfig, KubernetesService } from "../ import { KubernetesResource } from "../types" import { getKubernetesServiceStatus, deployKubernetesService } from "../kubernetes-module/handlers" import { DeployServiceParams } from "../../../types/plugin/service/deployService" +import { getModuleTypeUrl } from "../../../docs/common" export interface PersistentVolumeClaimSpec extends BaseVolumeSpec { dependencies: string[] @@ -35,11 +36,12 @@ type PersistentVolumeClaimModule = Module name: joiProviderName("maven-container"), }) +const moduleTypeUrl = getModuleTypeUrl("maven-container") + export const gardenPlugin = createGardenPlugin({ name: "maven-container", dependencies: ["container"], docs: dedent` - Adds the [maven-container module type](${DOCS_BASE_URL}/module-types/maven-container), which is a specialized version of the - \`container\` module type that has special semantics for building JAR files using Maven. + Adds the [maven-container module type](${moduleTypeUrl}), which is a specialized version of the \`container\` module type that has special semantics for building JAR files using Maven. - To use it, simply add the provider to your provider configuration, and refer to the - [maven-container module docs](${DOCS_BASE_URL}/module-types/maven-container) for details on how to configure the modules. + To use it, simply add the provider to your provider configuration, and refer to the [maven-container module docs](${moduleTypeUrl}) for details on how to configure the modules. `, createModuleTypes: [ diff --git a/garden-service/src/plugins/openfaas/openfaas.ts b/garden-service/src/plugins/openfaas/openfaas.ts index 70419e783a2..a3d83a51857 100644 --- a/garden-service/src/plugins/openfaas/openfaas.ts +++ b/garden-service/src/plugins/openfaas/openfaas.ts @@ -23,7 +23,7 @@ import { GetServiceStatusParams } from "../../types/plugin/service/getServiceSta import { GetServiceLogsParams } from "../../types/plugin/service/getServiceLogs" import { DeleteServiceParams } from "../../types/plugin/service/deleteService" import { HelmModuleConfig } from "../kubernetes/helm/config" -import { DEFAULT_API_VERSION, STATIC_DIR, DOCS_BASE_URL } from "../../constants" +import { DEFAULT_API_VERSION, STATIC_DIR } from "../../constants" import { ExecModuleConfig } from "../exec" import { ConfigureProviderParams, ConfigureProviderResult } from "../../types/plugin/provider/configureProvider" import { KubernetesDeployment } from "../kubernetes/types" @@ -47,17 +47,19 @@ import { LogEntry } from "../../logger/log-entry" import { Provider } from "../../config/provider" import { parse } from "url" import { trim } from "lodash" +import { getModuleTypeUrl } from "../../docs/common" const systemDir = join(STATIC_DIR, "openfaas", "system") +const moduleTypeUrl = getModuleTypeUrl("openfaas") export const gardenPlugin = createGardenPlugin({ name: "openfaas", configSchema: configSchema(), dependencies: ["kubernetes"], docs: dedent` - This provider adds support for [OpenFaaS](https://www.openfaas.com/). It adds the [\`openfaas\` module type](${DOCS_BASE_URL}/module-types/openfaas) and (by default) installs the \`faas-netes\` runtime to the project namespace. Each \`openfaas\` module maps to a single OpenFaaS function. + This provider adds support for [OpenFaaS](https://www.openfaas.com/). It adds the [\`openfaas\` module type](${moduleTypeUrl}) and (by default) installs the \`faas-netes\` runtime to the project namespace. Each \`openfaas\` module maps to a single OpenFaaS function. - See the reference below for configuration options for \`faas-netes\`, and the [module type docs](${DOCS_BASE_URL}/module-types/openfaas) for how to configure the individual functions. + See the reference below for configuration options for \`faas-netes\`, and the [module type docs](${moduleTypeUrl}) for how to configure the individual functions. Also see the [openfaas example project](/~https://github.com/garden-io/garden/tree/master/examples/openfaas) for a simple usage example. `, diff --git a/garden-service/test/unit/src/docs/table-of-contents.ts b/garden-service/test/unit/src/docs/table-of-contents.ts index bc7e0f4728e..e19e34e4408 100644 --- a/garden-service/test/unit/src/docs/table-of-contents.ts +++ b/garden-service/test/unit/src/docs/table-of-contents.ts @@ -15,20 +15,26 @@ describe("table of contents", () => { it("should return a correctly ordered table of contents", async () => { const testDocsDir = getDataDir("test-table-of-contents") const output = generateTableOfContents(testDocsDir) - expect(output).to.eql(dedent` + expect(output.trim()).to.eql(dedent` # Table of Contents - * [Directory 3](./3/README.md) - * [Directory 2](./2/README.md) - * [Directory 1](./1/README.md) - * [Directory 4](./4/README.md) - * [This goes first.](./4/2.md) - * [This goes second.](./4/1.md) - * [I have a title but no order.](./4/b.md) - * [I too have a title but no order.](./4/a.md) - * [X Something.md](./4/x-something.md) - * [Y Something.md](./4/y-something.md)\n + ## 🌳 Directory 3 + + ## 🌻 Directory 2 + + + ## 💐 Directory 1 + + + ## 🌿 Directory 4 + + * [This goes first.](./4/2.md) + * [This goes second.](./4/1.md) + * [I have a title but no order.](./4/b.md) + * [I too have a title but no order.](./4/a.md) + * [X Something.md](./4/x-something.md) + * [Y Something.md](./4/y-something.md) `) }) })