1 files changed, 57 insertions, 0 deletions

diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst
index ca9b864..b3b5e07 100644
--- a/docs/gl_objects/mrs.rst
+++ b/docs/gl_objects/mrs.rst
@@ -1,3 +1,5 @@
+.. _merge_requests_examples:
+
 ##############
 Merge requests
 ##############
@@ -5,6 +7,53 @@ Merge requests
 You can use merge requests to notify a project that a branch is ready for
 merging. The owner of the target projet can accept the merge request.
 
+Merge requests are linked to projects, but they can be listed globally or for
+groups.
+
+Group and global listing
+========================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.GroupMergeRequest`
+  + :class:`gitlab.v4.objects.GroupMergeRequestManager`
+  + :attr:`gitlab.v4.objects.Group.mergerequests`
+  + :class:`gitlab.v4.objects.MergeRequest`
+  + :class:`gitlab.v4.objects.MergeRequestManager`
+  + :attr:`gitlab.Gtilab.mergerequests`
+
+* GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html
+
+Examples
+--------
+
+List the merge requests available on the GitLab server::
+
+    mrs = gl.mergerequests.list()
+
+List the merge requests for a group::
+
+    group = gl.groups.get('mygroup')
+    mrs = group.mergerequests.list()
+
+.. note::
+
+   It is not possible to edit or delete ``MergeRequest`` and
+   ``GroupMergeRequest`` objects. You need to create a ``ProjectMergeRequest``
+   object to apply changes::
+
+       mr = group.mergerequests.list()[0]
+       project = gl.projects.get(mr.project_id, lazy=True)
+       editable_mr = project.mergerequests.get(mr.iid, lazy=True)
+       editable_mr.title = updated_title
+       editable_mr.save()
+
+Project merge requests
+======================
+
 Reference
 ---------
 
@@ -74,6 +123,14 @@ List commits of a MR::
 
     commits = mr.commits()
 
+List the changes of a MR::
+
+    changes = mr.changes()
+
+List the pipelines for a MR::
+
+    pipelines = mr.pipelines()
+
 List issues that will close on merge::
 
     mr.closes_issues()