Add support for triggering a new build

Fixes #184

2 files changed, 32 insertions, 11 deletions

diff --git a/docs/gl_objects/builds.py b/docs/gl_objects/builds.py
index 9f5ef12..911fc75 100644
--- a/docs/gl_objects/builds.py
+++ b/docs/gl_objects/builds.py
@@ -110,3 +110,9 @@ build.erase()
 # play
 build.play()
 # end play
+
+# trigger run
+p = gl.projects.get(project_id)
+p.trigger_build('master', trigger_token,
+                {'extra_var1': 'foo', 'extra_var2': 'bar'})
+# end trigger run
diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst
index 78412b4..b20ca77 100644
--- a/docs/gl_objects/builds.rst
+++ b/docs/gl_objects/builds.rst
@@ -5,10 +5,12 @@ Builds
 Build triggers
 ==============
 
-Use :class:`~gitlab.objects.ProjectTrigger` objects to manipulate build
-triggers. The :attr:`gitlab.Gitlab.project_triggers` and
-:attr:`gitlab.objects.Project.triggers` manager objects provide helper
-functions.
+Build triggers provide a way to interact with the GitLab CI. Using a trigger a
+user or an application can run a new build for a specific commit.
+
+* Object class: :class:`~gitlab.objects.ProjectTrigger`
+* Manager objects: :attr:`gitlab.Gitlab.project_triggers`,
+  :attr:`Project.triggers <gitlab.objects.Project.triggers>`
 
 Examples
 --------
@@ -40,10 +42,11 @@ Remove a trigger:
 Build variables
 ===============
 
-Use :class:`~gitlab.objects.ProjectVariable` objects to manipulate build
-variables. The :attr:`gitlab.Gitlab.project_variables` and
-:attr:`gitlab.objects.Project.variables` manager objects provide helper
-functions.
+You can associate variables to builds to modify the build script behavior.
+
+* Object class: :class:`~gitlab.objects.ProjectVariable`
+* Manager objects: :attr:`gitlab.Gitlab.project_variables`,
+  :attr:`gitlab.objects.Project.variables`
 
 Examples
 --------
@@ -81,13 +84,25 @@ Remove a variable:
 Builds
 ======
 
-Use :class:`~gitlab.objects.ProjectBuild` objects to manipulate builds. The
-:attr:`gitlab.Gitlab.project_builds` and :attr:`gitlab.objects.Project.builds`
-manager objects provide helper functions.
+Builds are associated to projects and commits. They provide information on the
+build that have been run, and methods to manipulate those builds.
+
+* Object class: :class:`~gitlab.objects.ProjectBuild`
+* Manager objects: :attr:`gitlab.Gitlab.project_builds`,
+  :attr:`gitlab.objects.Project.builds`
 
 Examples
 --------
 
+Build are usually automatically triggered, but you can explicitly trigger a
+new build:
+
+Trigger a new build on a project:
+
+.. literalinclude:: builds.py
+   :start-after: # trigger run
+   :end-before: # end trigger run
+
 List builds for the project:
 
 .. literalinclude:: builds.py