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

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

app/views/projects/triggers/index.html.haml

@@ -4,17 +4,26 @@
   .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
+    .panel.panel-default
+      .panel-heading
+        %h4.panel-title
+          Manage your project's triggers
+      .panel-body
         - if @triggers.any?
           .table-responsive
             %table.table
               %thead
-            %th Token
-            %th Last used
+                %th
+                  %strong Token
+                %th
+                  %strong Last used
                 %th
               = render partial: 'trigger', collection: @triggers, as: :trigger
         - else
@@ -22,13 +31,28 @@
             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'
+          = f.submit "Add trigger", class: 'btn btn-success'
+
+      .panel-footer
+
+        %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.
 
         %h5.prepend-top-default
-      Use CURL
+          Use cURL
 
         %p.light
-      Copy the token above, set your branch or tag name, and that reference will be rebuilt.
+          Copy one of the tokens above, set your branch or tag name, and that
+          reference will be rebuilt.
 
         %pre
           :plain
@@ -42,13 +66,13 @@
         %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.
+          of another project, include the following snippet.
+          The project will be rebuilt at the end of the build.
 
         %pre
           :plain
-        trigger:
-          type: deploy
+            trigger_build:
+              stage: deploy
               script:
                 - "curl -X POST -F token=TOKEN -F ref=REF_NAME #{builds_trigger_url(@project.id)}"
         %h5.prepend-top-default

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.

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