feat: add pipeline templates to guide (#591)

Co-authored-by: ppaul <[email protected]>
Co-authored-by: Vonny Jap <[email protected]>

docs/_data/menu.yml

@@ -45,7 +45,11 @@
     - title: "Environment Variables"
       url: "/user-guide/environment-variables"
     - title: "Templates"
-      url: "/user-guide/templates"
+      subcategories:
+        - title: Job Templates
+          url: "/user-guide/templates/job-templates"
+        - title: Pipeline Templates
+          url: "/user-guide/templates/pipeline-templates"
     - title: "Commands"
       url: "/user-guide/commands"
     - title: "Local Build"

docs/user-guide/configuration/jobconfiguration.md

@@ -4,26 +4,29 @@ title: Job Configuration
 category: User Guide
 menu: menu
 toc:
-    - title: Job Configuration
-      url: "#job-configuration"
-    - title: Image
-      url: "#image"
-    - title: Steps
-      url: "#steps"
-    - title: Teardown
-      url: "#teardown"
-      subitem: 1
-    - title: Template
-      url: "#template"
-      subitem: 1
-    - title: Shared Configuration
-      url: "#shared-configuration"
-      subitem: 1
+  - title: Job Configuration
+    url: "#job-configuration"
+  - title: Image
+    url: "#image"
+  - title: Steps
+    url: "#steps"
+  - title: Teardown
+    url: "#teardown"
+    subitem: 1
+  - title: Template
+    url: "#template"
+    subitem: 1
+  - title: Shared Configuration
+    url: "#shared-configuration"
+    subitem: 1
 ---
+
 # Job Configuration
+
 Jobs are how you define what happens in every build. Every job configuration must consist of an `image` and a list of `steps`, or a `template`. It also defines trigger requirement for the job using `requires`. See [workflow](./workflow) for detailed usage of `requires` to create pipeline workflow.
 
 #### Example
+
 ```
 jobs:
     main:
@@ -38,9 +41,11 @@ jobs:
 ```
 
 ## Image
+
 The `image` configuration refers to a docker image, e.g. an container from [hub.docker.com](https://hub.docker.com). You can specify an image from a custom registry by specifying the full url to that image.
 
 #### Example
+
 ```
 jobs:
     main:
@@ -51,6 +56,7 @@ jobs:
 ```
 
 ## Steps
+
 Steps are the list of instructions you want to execute in your build. These should be defined as:
 `step_name: step_command`. Steps will be executed in the order they are defined. Current working directory and environment variables are passed between steps.
 
@@ -61,6 +67,7 @@ Example repo: <https://github.com/screwdriver-cd-test/user-teardown-example>
 By default, instructions in steps are executed using the Bourne shell (`/bin/sh`). If you prefer your build to use a different shell, you can configure `USER_SHELL_BIN`. For instance, to use capabilities that Bash provides but the Bourne shell does not, specify `USER_SHELL_BIN: bash` in a job's environment.
 
 #### Example
+
 ```
 jobs:
     main:
@@ -83,16 +90,21 @@ jobs:
 ```
 
 ### Teardown
+
 The teardown steps run a set of Screwdriver bookend steps after the build steps are completed or aborted or failed. These steps are implicitly added at the end of job and start with `sd-teardown-` or `teardown-`. The pod/container is removed after these steps are completed. In case of aborted builds, we can also configure the grace period of the pod before termination during which the teardown steps will be executed. See the `screwdriver.cd/terminationGracePeriodSeconds` [annotation](/user-guide/configuration/annotations) for detailed usage.
 
 ### Template
-You can also use [templates](../templates) in a job configuration.
+
+You can also use [templates](../templates/job-templates) in a job configuration.
 
 # Shared Configuration
+
 The `shared` configuration is a special job configuration section that is applied to all jobs. Configuration that is specified in a job configuration will override the same configuration in `shared`.
 
 #### Example
+
 The following example defines a shared configuration for `image` and `steps`, which is used by the main and main2 jobs.
+
 ```
 shared:
     image: node:8
@@ -112,6 +124,7 @@ jobs:
 ```
 
 The above example would be equivalent to:
+
 ```
 jobs:
     main:
@@ -129,11 +142,11 @@ jobs:
 
 ```
 
-
 ### See also:
-* [Annotations](./annotations) - Freeform key/value store, often used to configure build execution settings
-* [Environment](./environment) - Define environment variables for jobs
-* [Secrets](./secrets) - Securely pass secrets as environment variables into the build
-* [Settings](./settings) - Define configuration of build plugins
-* [Templates](../templates) - Common, community supported job configurations
-* [Workflow](./workflow) - Define the path of the pipeline
+
+- [Annotations](./annotations) - Freeform key/value store, often used to configure build execution settings
+- [Environment](./environment) - Define environment variables for jobs
+- [Secrets](./secrets) - Securely pass secrets as environment variables into the build
+- [Settings](./settings) - Define configuration of build plugins
+- [Job Templates](../templates/job-templates) - Common, community supported job configurations
+- [Workflow](./workflow) - Define the path of the pipeline

docs/user-guide/templates.md → docs/user-guide/templates/job-templates.md

@@ -1,11 +1,11 @@
 ---
 layout: main
-title: Templates
+title: Job Templates
 category: User Guide
 menu: menu
 toc:
-    - title: Templates
-      url: "#templates"
+    - title: Job Templates
+      url: "#job-templates"
     - title: Finding templates
       url: "#finding-templates"
     - title: Using a template
@@ -64,16 +64,16 @@ toc:
     - title: Removing a template
       url: "#removing-a-template"
 ---
-# Templates
+# Job Templates
 
-Templates are snippets of predefined code that people can use to replace a job definition in a [screwdriver.yaml](./configuration). A template contains a series of predefined steps along with a selected Docker image.
+Templates are snippets of predefined code that people can use to replace a job definition in a [screwdriver.yaml](../configuration). A template contains a series of predefined steps along with a selected Docker image.
 
 ## Finding templates
 
-To figure out which templates already exist, you can make a `GET` call to the `/templates` [API](./api) endpoint. You can also see templates in the UI at `<YOUR_UI_URL>/templates`.
+To figure out which templates already exist, you can make a `GET` call to the `/templates` [API](../api) endpoint. You can also see templates in the UI at `<YOUR_UI_URL>/templates`.
 
 Example templates page:
-![Templates](assets/templates.png)
+![Templates](../assets/templates.png)
 
 ## Using a template
 
@@ -184,7 +184,7 @@ jobs:
 
 ### Merging with shared steps
 
-When overriding Template steps, a job can get the step definitions from either `shared.steps` or `job.steps` with precedence for `steps` defined in `job` section. This follows the same order of precedence for step definitions without using a template. Users can change this behavior using [annotation](./configuration/annotations) `screwdriver.cd/mergeSharedSteps: true`. When `true` steps in `shared` and `job` sections are merged when a Template is used.
+When overriding Template steps, a job can get the step definitions from either `shared.steps` or `job.steps` with precedence for `steps` defined in `job` section. This follows the same order of precedence for step definitions without using a template. Users can change this behavior using [annotation](../configuration/annotations) `screwdriver.cd/mergeSharedSteps: true`. When `true` steps in `shared` and `job` sections are merged when a Template is used.
 
 
 #### Example
@@ -210,7 +210,6 @@ The following example defines a merged shared configuration for `image` and `ste
 ```yaml
 shared:
     image: node:8
-    template: nodejs/test
     steps:
         - init: npm install
         - pretest: npm lint
@@ -245,7 +244,6 @@ jobs:
         requires: [main]
         image: node:8
         steps:
-             - init: npm install
              - pretest: npm lint
              - test: echo Skipping test
 
@@ -401,7 +399,7 @@ config:
 ```
 
 #### Template parameters
-You can define [parameters](./configuration/parameters) that can be used in the steps.  
+You can define [parameters](../configuration/parameters) that can be used in the steps.  
 
 Example `sd-template.yaml`:
 ```yaml
@@ -633,7 +631,7 @@ _Note: You cannot test your template in the same pipeline, as template step expa
 
 ## Using the build cache
 
-To use the [build cache feature](./configuration/build-cache), the [store-cli command](https://github.com/screwdriver-cd/store-cli) can be invoked in a step. For instance, if you are caching your `node_modules/` folder, you can specify a step before the `npm install` command that downloads the cache and another step afterwards that uploads the cache. You can also move the uploading cache step to a teardown with the `teardown-` prefix.
+To use the [build cache feature](../configuration/build-cache), the [store-cli command](https://github.com/screwdriver-cd/store-cli) can be invoked in a step. For instance, if you are caching your `node_modules/` folder, you can specify a step before the `npm install` command that downloads the cache and another step afterwards that uploads the cache. You can also move the uploading cache step to a teardown with the `teardown-` prefix.
 
 ```yaml
 config:
@@ -654,4 +652,4 @@ Or, you can remove your template and all its associated tags and versions by cli
 
 _Note: Do not delete your template pipeline beforehand, because it is required to determine who has permission to delete the template._
 
-![Removing](assets/delete-template.png)
+![Removing](../assets/delete-template.png)