improvement(plugins): define schemas for module outputs and add docs

Closes #670

docs/reference/module-types/container.md

@@ -10,11 +10,13 @@ other module types like [helm](https://docs.garden.io/reference/module-types/hel
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
-The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available
+The [first section](#configuration-keys) lists and describes the available
 schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema.
 
-## Configuration keys
+`container` modules also export values that are available via the `${modules.<module-name>.outputs}`. See the
+[Outputs](#outputs) section below for details.
 
+## Configuration keys
 
 ### `apiVersion`
 
@@ -946,4 +948,26 @@ tasks:
     command:
     args:
     env: {}
-```
+```
+
+## Outputs
+
+The following keys are available via the `${modules.<module-name>.outputs}` template string key for `container`
+modules.
+
+### `modules.<module-name>.outputs.local-image-name`
+
+The name of the image (without tag/version) that the module uses for local builds and deployments.
+
+| Type | Required |
+| ---- | -------- |
+| `string` | Yes
+
+### `modules.<module-name>.outputs.deployment-image-name`
+
+The name of the image (without tag/version) that the module will use during deployment.
+
+| Type | Required |
+| ---- | -------- |
+| `string` | Yes
+

docs/reference/module-types/exec.md

@@ -5,12 +5,11 @@ type fits your needs, and you just need to execute something (as opposed to depl
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
-The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available
+The [first section](#configuration-keys) lists and describes the available
 schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema.
 
 ## Configuration keys
 
-
 ### `apiVersion`
 
 The schema version of this module's config (currently not used).
@@ -351,4 +350,4 @@ tests:
     timeout: null
     command:
     env: {}
-```
+```

docs/reference/module-types/helm.md

@@ -5,11 +5,13 @@ Refer to the [Helm guide](https://docs.garden.io/using-garden/using-helm-charts)
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
-The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available
+The [first section](#configuration-keys) lists and describes the available
 schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema.
 
-## Configuration keys
+`helm` modules also export values that are available via the `${modules.<module-name>.outputs}`. See the
+[Outputs](#outputs) section below for details.
 
+## Configuration keys
 
 ### `apiVersion`
 
@@ -678,4 +680,18 @@ tests:
     env: {}
 version:
 values: {}
-```
+```
+
+## Outputs
+
+The following keys are available via the `${modules.<module-name>.outputs}` template string key for `helm`
+modules.
+
+### `modules.<module-name>.outputs.release-name`
+
+The Helm release name of the service.
+
+| Type | Required |
+| ---- | -------- |
+| `string` | Yes
+

docs/reference/module-types/kubernetes.md

@@ -13,12 +13,11 @@ If you need more advanced templating features you can use the
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
-The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available
+The [first section](#configuration-keys) lists and describes the available
 schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema.
 
 ## Configuration keys
 
-
 ### `apiVersion`
 
 The schema version of this module's config (currently not used).
@@ -268,4 +267,4 @@ manifests:
     metadata:
       name:
 files: []
-```
+```

docs/reference/module-types/maven-container.md

@@ -15,11 +15,13 @@ The provider will automatically fetch and cache Maven and the appropriate OpenJD
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
-The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available
+The [first section](#configuration-keys) lists and describes the available
 schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema.
 
-## Configuration keys
+`maven-container` modules also export values that are available via the `${modules.<module-name>.outputs}`. See the
+[Outputs](#outputs) section below for details.
 
+## Configuration keys
 
 ### `apiVersion`
 
@@ -984,4 +986,26 @@ tasks:
 jarPath:
 jdkVersion: 8
 mvnOpts: []
-```
+```
+
+## Outputs
+
+The following keys are available via the `${modules.<module-name>.outputs}` template string key for `maven-container`
+modules.
+
+### `modules.<module-name>.outputs.local-image-name`
+
+The name of the image (without tag/version) that the module uses for local builds and deployments.
+
+| Type | Required |
+| ---- | -------- |
+| `string` | Yes
+
+### `modules.<module-name>.outputs.deployment-image-name`
+
+The name of the image (without tag/version) that the module will use during deployment.
+
+| Type | Required |
+| ---- | -------- |
+| `string` | Yes
+

docs/reference/module-types/openfaas.md

@@ -4,12 +4,11 @@
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
-The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available
+The [first section](#configuration-keys) lists and describes the available
 schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema.
 
 ## Configuration keys
 
-
 ### `apiVersion`
 
 The schema version of this module's config (currently not used).
@@ -190,4 +189,4 @@ build:
       copy:
         - source:
           target: ''
-```
+```

docs/reference/template-strings.md

@@ -7,6 +7,10 @@ Note that there are three sections below, because Project configs and Module con
 them, and additional keys are available under `providers` in Project configs.
 Please make sure to refer to the correct section.
 
+Modules are able to reference defined `outputs` from other modules, via the `${modules.<module-name>.outputs}` key.
+For details on which outputs are available for a module type, please refer to the
+[reference](https://docs.garden.io/reference/module-types) docs for the module type and look for the _Outputs_ section.
+
 ## Project configuration context
 
 The following keys are available in template strings anywhere in Project `garden.yml` config files:

garden-service/src/actions.ts

@@ -261,6 +261,7 @@ export class ActionHelper implements TypeGuard {
       moduleType,
       defaultHandler: async ({ }) => ({
         docs: "",
+        outputsSchema: Joi.object().options({ allowUnknown: true }),
         schema: Joi.object().options({ allowUnknown: true }),
       }),
     })

garden-service/src/config/config-context.ts

@@ -308,7 +308,10 @@ class ModuleContext extends ConfigContext {
 
   @schema(
     joiIdentifierMap(joiPrimitive())
-      .description("The outputs defined by the module (see individual plugins for details).")
+      .description(
+        "The outputs defined by the module (see individual module type " +
+        "[references](https://docs.garden.io/reference/module-types) for details).",
+      )
       .example(exampleOutputs),
   )
   public outputs: PrimitiveMap

garden-service/src/docs/config.ts

@@ -209,21 +209,22 @@ function getParentDescriptions(
   return descriptions
 }
 
-function renderMarkdownTitle(description: NormalizedDescription) {
+function renderMarkdownTitle(description: NormalizedDescription, prefix = "") {
   const parentDescriptions = getParentDescriptions(description)
-  return parentDescriptions.length > 0
+  const title = parentDescriptions.length > 0
     ? `${parentDescriptions.map(d => d.formattedName).join(".")}.${description.formattedName}`
     : description.name
+  return prefix + title
 }
 
 function renderMarkdownLink(description: NormalizedDescription) {
   const path = renderMarkdownTitle(description).replace(/\s+/g, "-").toLowerCase()
   return `[${description.name}](#${path})`
 }
 
-function makeMarkdownDescription(description: NormalizedDescription) {
+function makeMarkdownDescription(description: NormalizedDescription, titlePrefix = "") {
   const parentDescriptions = getParentDescriptions(description)
-  const title = renderMarkdownTitle(description)
+  const title = renderMarkdownTitle(description, titlePrefix)
   const breadCrumbs = parentDescriptions.length > 0
     ? parentDescriptions
       .map(renderMarkdownLink)
@@ -359,12 +360,12 @@ export function renderSchemaDescriptionYaml(
  * The config reference contains a list of keys and their description in Markdown
  * and a YAML schema.
  */
-export function renderConfigReference(configSchema: Joi.ObjectSchema) {
+export function renderConfigReference(configSchema: Joi.ObjectSchema, titlePrefix = "") {
   const partialTemplatePath = resolve(TEMPLATES_DIR, "config-partial.hbs")
   const normalizedDescriptions = normalizeDescriptions(configSchema.describe())
 
   const yaml = renderSchemaDescriptionYaml(normalizedDescriptions, { showComment: false })
-  const keys = normalizedDescriptions.map(makeMarkdownDescription)
+  const keys = normalizedDescriptions.map(d => makeMarkdownDescription(d, titlePrefix))
 
   const template = handlebars.compile(readFileSync(partialTemplatePath).toString())
   return { markdownReference: template({ keys }), yaml }
@@ -385,11 +386,14 @@ function renderProviderReference(schema: Joi.ObjectSchema, name: string) {
  * Generates the module types reference from the module-type.hbs template.
  * The reference includes the rendered output from the config-partial.hbs template.
  */
-function renderModuleTypeReference(schema: Joi.ObjectSchema, name: string, docs: string) {
+function renderModuleTypeReference(
+  schema: Joi.ObjectSchema, outputsSchema: Joi.ObjectSchema, name: string, docs: string,
+) {
   const moduleTemplatePath = resolve(TEMPLATES_DIR, "module-type.hbs")
   const { markdownReference, yaml } = renderConfigReference(schema)
+  const outputsReference = renderConfigReference(outputsSchema, "modules.<module-name>.outputs.").markdownReference
   const template = handlebars.compile(readFileSync(moduleTemplatePath).toString())
-  return template({ name, docs, markdownReference, yaml })
+  return template({ name, docs, markdownReference, yaml, outputsReference })
 }
 
 /**
@@ -444,10 +448,15 @@ export async function writeConfigReferenceDocs(docsRoot: string) {
   for (const { name } of moduleTypes) {
     const path = resolve(moduleTypeDir, `${name}.md`)
     const actions = await garden.getActionHelper()
-    const { docs, schema, title } = await actions.describeType(name)
+    const { docs, outputsSchema, schema, title } = await actions.describeType(name)
 
     console.log("->", path)
-    writeFileSync(path, renderModuleTypeReference(populateModuleSchema(schema), name, docs))
+    writeFileSync(path, renderModuleTypeReference(
+      populateModuleSchema(schema),
+      outputsSchema,
+      name,
+      docs,
+    ))
 
     readme.push(`* [${title || startCase(name.replace("-", " "))}](./${name}.md)`)
   }

garden-service/src/docs/templates/module-type.hbs

@@ -4,14 +4,26 @@
 
 Below is the schema reference. For an introduction to configuring Garden modules, please look at our [Configuration
 guide](../../using-garden/configuration-files.md).
-The reference is divided into two sections. The [first section](#configuration-keys) lists and describes the available
+The [first section](#configuration-keys) lists and describes the available
 schema keys. The [second section](#complete-yaml-schema) contains the complete YAML schema.
 
-## Configuration keys
+{{#if outputsReference}}
+`{{{name}}}` modules also export values that are available via the `${modules.<module-name>.outputs}`. See the
+[Outputs](#outputs) section below for details.
 
+{{/if}}
+## Configuration keys
 {{{markdownReference}}}
 
 ## Complete YAML schema
 ```yaml
 {{{yaml}}}
-```
+```
+{{#if outputsReference}}
+
+## Outputs
+
+The following keys are available via the `${modules.<module-name>.outputs}` template string key for `{{{name}}}`
+modules.
+{{{outputsReference}}}
+{{/if}}

garden-service/src/docs/templates/template-strings.hbs

@@ -7,6 +7,10 @@ Note that there are three sections below, because Project configs and Module con
 them, and additional keys are available under `providers` in Project configs.
 Please make sure to refer to the correct section.
 
+Modules are able to reference defined `outputs` from other modules, via the `${modules.<module-name>.outputs}` key.
+For details on which outputs are available for a module type, please refer to the
+[reference](https://docs.garden.io/reference/module-types) docs for the module type and look for the _Outputs_ section.
+
 ## Project configuration context
 
 The following keys are available in template strings anywhere in Project `garden.yml` config files:

garden-service/src/plugins/container/container.ts

@@ -7,6 +7,7 @@
  */
 
 import dedent = require("dedent")
+import * as Joi from "joi"
 import { keyBy } from "lodash"
 
 import { ConfigurationError } from "../../exceptions"
@@ -19,6 +20,18 @@ import { ConfigureModuleParams } from "../../types/plugin/module/configure"
 import { PublishModuleParams } from "../../types/plugin/module/publishModule"
 import { HotReloadServiceParams } from "../../types/plugin/service/hotReloadService"
 
+export const containerModuleOutputsSchema = Joi.object()
+  .keys({
+    "local-image-name": Joi.string()
+      .required()
+      .description(
+        "The name of the image (without tag/version) that the module uses for local builds and deployments.",
+      ),
+    "deployment-image-name": Joi.string()
+      .required()
+      .description("The name of the image (without tag/version) that the module will use during deployment."),
+  })
+
 export async function configureContainerModule({ ctx, moduleConfig }: ConfigureModuleParams<ContainerModule>) {
   // validate hot reload configuration
   // TODO: validate this when validating this action's output
@@ -121,6 +134,7 @@ export async function configureContainerModule({ ctx, moduleConfig }: ConfigureM
   )
 
   moduleConfig.outputs = {
+    "local-image-name": await containerHelpers.getLocalImageName(moduleConfig),
     "deployment-image-name": deploymentImageName,
   }
 
@@ -178,6 +192,7 @@ async function describeType() {
       other module types like [helm](https://docs.garden.io/reference/module-types/helm) or
       [kubernetes](https://github.com/garden-io/garden/blob/master/docs/reference/module-types/kubernetes.md).
     `,
+    outputsSchema: containerModuleOutputsSchema,
     schema: containerModuleSpecSchema,
   }
 }