Merge branch '21773-document-trigger-section-in-gitlab-ci-yml-docs' into 'master'

Better document triggers docs

## What does this MR do?

- Refactor the triggers page view
- Replace old images with new ones
- Mention triggers in `ci/yaml/README.md`

## Screenshots (if relevant)

The new triggers views contains more information and is prettier :)

## Before

![screenshot-localhost_3000_2016-09-06_10-53-10](/uploads/8f45a0e21a31f1819af1739f7af8afd0/screenshot-localhost_3000_2016-09-06_10-53-10.png)

# After

![screenshot-localhost_3000_2016-09-06_10-36-34](/uploads/2bbe2801b0f959851a8cfa5a8a14623d/screenshot-localhost_3000_2016-09-06_10-36-34.png)

## Does this MR meet the acceptance criteria?

- [x] [CHANGELOG](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CHANGELOG) entry added
- [x] [Documentation created/updated](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/development/doc_styleguide.md)
- [x] Conform by the [merge request performance guides](http://docs.gitlab.com/ce/development/merge_request_performance_guidelines.html)
- [x] Conform by the [style guides](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#style-guides)
- [x] Branch has no merge conflicts with `master` (if you do - rebase it please)
- [x] [Squashed related commits together](https://git-scm.com/book/en/Git-Tools-Rewriting-History#Squashing-Commits)

## What are the relevant issue numbers?

Closes #21773

See merge request !6217

8 files changed, 89 insertions, 99 deletions

diff --git a/CHANGELOG b/CHANGELOG
index f54a17e1ea2..a9783622f35 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -84,6 +84,7 @@ v 8.12.0 (unreleased)
   - User can edit closed MR with deleted fork (Katarzyna Kobierska Ula Budziszewska) !5496
   - Fixed invisible scroll controls on build page on iPhone
   - Fix error on raw build trace download for old builds stored in database !4822
+  - Refactor the triggers page and documentation !6217
 
 v 8.11.5 (unreleased)
   - Optimize branch lookups and force a repository reload for Repository#find_branch
diff --git a/app/views/projects/triggers/index.html.haml b/app/views/projects/triggers/index.html.haml
index 7f3de47d7df..f6e0b0a7c8a 100644
--- a/app/views/projects/triggers/index.html.haml
+++ b/app/views/projects/triggers/index.html.haml
@@ -4,65 +4,89 @@
   .col-lg-3
     %h4.prepend-top-0
       = page_title
-    %p
-      Triggers can force a specific branch or tag to rebuild with an API call.
+    %p.prepend-top-20
+      Triggers can force a specific branch or tag to get rebuilt with an API call.
+    %p.append-bottom-0
+      = succeed '.' do
+        Learn more in the
+        = link_to 'triggers documentation', help_page_path('ci/triggers/README'), target: '_blank'
   .col-lg-9
-    %h5.prepend-top-0
-      Your triggers
-    - if @triggers.any?
-      .table-responsive
-        %table.table
-          %thead
-            %th Token
-            %th Last used
-            %th
-          = render partial: 'trigger', collection: @triggers, as: :trigger
-    - else
-      %p.settings-message.text-center.append-bottom-default
-        No triggers have been created yet. Add one using the button below.
+    .panel.panel-default
+      .panel-heading
+        %h4.panel-title
+          Manage your project's triggers
+      .panel-body
+        - if @triggers.any?
+          .table-responsive
+            %table.table
+              %thead
+                %th
+                  %strong Token
+                %th
+                  %strong Last used
+                %th
+              = render partial: 'trigger', collection: @triggers, as: :trigger
+        - else
+          %p.settings-message.text-center.append-bottom-default
+            No triggers have been created yet. Add one using the button below.
 
-    = form_for @trigger, url: url_for(controller: 'projects/triggers', action: 'create') do |f|
-      = f.submit "Add Trigger", class: 'btn btn-success'
+        = form_for @trigger, url: url_for(controller: 'projects/triggers', action: 'create') do |f|
+          = f.submit "Add trigger", class: 'btn btn-success'
 
-    %h5.prepend-top-default
-      Use CURL
+      .panel-footer
 
-    %p.light
-      Copy the token above, set your branch or tag name, and that reference will be rebuilt.
+        %p
+          In the following examples, you can see the exact API call you need to
+          make in order to rebuild a specific
+          %code ref
+          (branch or tag) with a trigger token.
+        %p
+          All you need to do is replace the
+          %code TOKEN
+          and
+          %code REF_NAME
+          with the trigger token and the branch or tag name respectively.
 
-    %pre
-      :plain
-        curl -X POST \
-             -F token=TOKEN \
-             -F ref=REF_NAME \
-             #{builds_trigger_url(@project.id)}
-    %h5.prepend-top-default
-      Use .gitlab-ci.yml
+        %h5.prepend-top-default
+          Use cURL
 
-    %p.light
-      In the
-      %code .gitlab-ci.yml
-      of the dependent project, include the following snippet.
-      The project will rebuild at the end of the build.
+        %p.light
+          Copy one of the tokens above, set your branch or tag name, and that
+          reference will be rebuilt.
 
-    %pre
-      :plain
-        trigger:
-          type: deploy
-          script:
-            - "curl -X POST -F token=TOKEN -F ref=REF_NAME #{builds_trigger_url(@project.id)}"
-    %h5.prepend-top-default
-      Pass build variables
+        %pre
+          :plain
+            curl -X POST \
+                 -F token=TOKEN \
+                 -F ref=REF_NAME \
+                 #{builds_trigger_url(@project.id)}
+        %h5.prepend-top-default
+          Use .gitlab-ci.yml
 
-    %p.light
-      Add
-      %code variables[VARIABLE]=VALUE
-      to an API request. Variable values can be used to distinguish between triggered builds and normal builds.
+        %p.light
+          In the
+          %code .gitlab-ci.yml
+          of another project, include the following snippet.
+          The project will be rebuilt at the end of the build.
 
-    %pre.append-bottom-0
-      :plain
-        curl -X POST \
-             -F token=TOKEN \
-             -F "ref=REF_NAME" \
-             -F "variables[RUN_NIGHTLY_BUILD]=true" \
-             #{builds_trigger_url(@project.id)}
+        %pre
+          :plain
+            trigger_build:
+              stage: deploy
+              script:
+                - "curl -X POST -F token=TOKEN -F ref=REF_NAME #{builds_trigger_url(@project.id)}"
+        %h5.prepend-top-default
+          Pass build variables
+
+        %p.light
+          Add
+          %code variables[VARIABLE]=VALUE
+          to an API request. Variable values can be used to distinguish between triggered builds and normal builds.
+
+        %pre.append-bottom-0
+          :plain
+            curl -X POST \
+                 -F token=TOKEN \
+                 -F "ref=REF_NAME" \
+                 -F "variables[RUN_NIGHTLY_BUILD]=true" \
+                 #{builds_trigger_url(@project.id)}
diff --git a/doc/ci/triggers/img/builds_page.png b/doc/ci/triggers/img/builds_page.png
index 2dee8ee6107..c2cf4b1852c 100644
--- a/doc/ci/triggers/img/builds_page.png
+++ b/doc/ci/triggers/img/builds_page.png
diff --git a/doc/ci/triggers/img/trigger_single_build.png b/doc/ci/triggers/img/trigger_single_build.png
index baf3fc183d8..fa86f0fee3d 100644
--- a/doc/ci/triggers/img/trigger_single_build.png
+++ b/doc/ci/triggers/img/trigger_single_build.png
diff --git a/doc/ci/triggers/img/trigger_variables.png b/doc/ci/triggers/img/trigger_variables.png
index 908355c33a5..b2fcc65d304 100644
--- a/doc/ci/triggers/img/trigger_variables.png
+++ b/doc/ci/triggers/img/trigger_variables.png
diff --git a/doc/ci/triggers/img/triggers_page.png b/doc/ci/triggers/img/triggers_page.png
index 69cec5cdebf..438f285ae2d 100644
--- a/doc/ci/triggers/img/triggers_page.png
+++ b/doc/ci/triggers/img/triggers_page.png
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 58d5306f12a..ff4c8ddc54b 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -6,50 +6,6 @@ GitLab Runner to manage your project's builds.
 If you want a quick introduction to GitLab CI, follow our
 [quick start guide](../quick_start/README.md).
 
----
-
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
-
-- [.gitlab-ci.yml](#gitlab-ci-yml)
-    - [image and services](#image-and-services)
-    - [before_script](#before_script)
-    - [after_script](#after_script)
-    - [stages](#stages)
-    - [types](#types)
-    - [variables](#variables)
-    - [cache](#cache)
-        - [cache:key](#cache-key)
-- [Jobs](#jobs)
-    - [script](#script)
-    - [stage](#stage)
-    - [only and except](#only-and-except)
-    - [job variables](#job-variables)
-    - [tags](#tags)
-    - [allow_failure](#allow_failure)
-    - [when](#when)
-        - [Manual actions](#manual-actions)
-    - [environment](#environment)
-    - [artifacts](#artifacts)
-        - [artifacts:name](#artifacts-name)
-        - [artifacts:when](#artifacts-when)
-        - [artifacts:expire_in](#artifacts-expire_in)
-    - [dependencies](#dependencies)
-    - [before_script and after_script](#before_script-and-after_script)
-- [Git Strategy](#git-strategy)
-- [Shallow cloning](#shallow-cloning)
-- [Hidden keys](#hidden-keys)
-- [Special YAML features](#special-yaml-features)
-    - [Anchors](#anchors)
-- [Validate the .gitlab-ci.yml](#validate-the-gitlab-ci-yml)
-- [Skipping builds](#skipping-builds)
-- [Examples](#examples)
-
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
-
----
-
 ## .gitlab-ci.yml
 
 From version 7.12, GitLab CI uses a [YAML](https://en.wikipedia.org/wiki/YAML)
@@ -183,7 +139,7 @@ Alias for [stages](#stages).
 Introduced in GitLab Runner v0.5.0.
 
 GitLab CI allows you to add variables to `.gitlab-ci.yml` that are set in the
-build environment. The variables are stored in the git repository and are meant
+build environment. The variables are stored in the Git repository and are meant
 to store non-sensitive project configuration, for example:
 
 ```yaml
@@ -198,6 +154,8 @@ thus allowing to fine tune them.
 
 Variables can be also defined on [job level](#job-variables).
 
+[Learn more about variables.](../variables/README.md)
+
 ### cache
 
 >**Note:**
@@ -1086,6 +1044,13 @@ test:mysql:
 
 You can see that the hidden keys are conveniently used as templates.
 
+## Triggers
+
+Triggers can be used to force a rebuild of a specific branch, tag or commit,
+with an API call.
+
+[Read more in the triggers documentation.](../triggers/README.md)
+
 ## Validate the .gitlab-ci.yml
 
 Each instance of GitLab CI has an embedded debug tool called Lint.
diff --git a/spec/features/triggers_spec.rb b/spec/features/triggers_spec.rb
index 3cbc8253ad6..72354834c5a 100644
--- a/spec/features/triggers_spec.rb
+++ b/spec/features/triggers_spec.rb
@@ -12,7 +12,7 @@ describe 'Triggers' do
 
   context 'create a trigger' do
     before do
-      click_on 'Add Trigger'
+      click_on 'Add trigger'
       expect(@project.triggers.count).to eq(1)
     end