docs: add MR API

Gauvain Pocentek · Gauvain Pocentek · commit 5614a7c9bf62 · 2016-08-07T21:49:44.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -14,6 +14,7 @@ API objects manipulation
    gl_objects/issues
    gl_objects/labels
    gl_objects/licenses
+   gl_objects/mrs
    gl_objects/namespaces
    gl_objects/projects
    gl_objects/runners
diff --git a/docs/gl_objects/mrs.py b/docs/gl_objects/mrs.py
@@ -0,0 +1,61 @@
+# list
+mrs = gl.project_mergerequests.list(project_id=1)
+# or
+mrs = project.mergerequests.list()
+# end list
+
+# filtered list
+mrs = project.mergerequests.list(state='merged', order_by='updated_at')
+# end filtered list
+
+# get
+mr = gl.project_mergerequests.get(mr_id, project_id=1)
+# or
+mr = project.mergerequests.get(mr_id)
+# end get
+
+# create
+mr = gl.project_mergerequests.create({'source_branch': 'cool_feature',
+                                      'target_branch': 'master',
+                                      'title': 'merge cool feature'},
+                                     project_id=1)
+# or
+mr = project.mergerequests.create({'source_branch': 'cool_feature',
+                                   'target_branch': 'master',
+                                   'title': 'merge cool feature'})
+# end create
+
+# update
+mr.description = 'New description'
+mr.save()
+# end update
+
+# state
+mr.state_event = 'close'  # or 'reopen'
+mr.save()
+# end state
+
+# delete
+gl.project_mergerequests.delete(mr_id, project_id=1)
+# or
+project.mergerequests.delete(mr_id)
+# or
+mr.delete()
+# end delete
+
+# merge
+mr.merge()
+# end merge
+
+# cancel
+mr.cancel_merge_when_build_succeeds()
+# end cancel
+
+# issues
+mr.closes_issues()
+# end issues
+
+# subscribe
+mr.subscribe()
+mr.unsubscribe()
+# end subscribe
diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst
@@ -0,0 +1,85 @@
+##############
+Merge requests
+##############
+
+Use :class:`~gitlab.objects.ProjectMergeRequest` objects to manipulate MRs for
+projects. The :attr:`gitlab.Gitlab.project_mergerequests` and
+:attr:`Project.mergerequests <gitlab.objects.Project.mergerequests>` manager
+objects provide helper functions.
+
+Examples
+--------
+
+List MRs for a project:
+
+.. literalinclude:: mrs.py
+   :start-after: # list
+   :end-before: # end list
+
+You can filter and sort the returned list with the following parameters:
+
+* ``iid``: iid (unique ID for the project) of the MR
+* ``state``: state of the MR. It can be one of ``all``, ``merged``, '``opened``
+  or ``closed``
+* ``order_by``: sort by ``created_at`` or ``updated_at``
+* ``sort``: sort order (``asc`` or ``desc``)
+
+For example:
+
+.. literalinclude:: mrs.py
+   :start-after: # list
+   :end-before: # end list
+
+Get a single MR:
+
+.. literalinclude:: mrs.py
+   :start-after: # get
+   :end-before: # end get
+
+Create a MR:
+
+.. literalinclude:: mrs.py
+   :start-after: # create
+   :end-before: # end create
+
+Update a MR:
+
+.. literalinclude:: mrs.py
+   :start-after: # update
+   :end-before: # end update
+
+Change the state of a MR (close or reopen):
+
+.. literalinclude:: mrs.py
+   :start-after: # state
+   :end-before: # end state
+
+Delete a MR:
+
+.. literalinclude:: mrs.py
+   :start-after: # delete
+   :end-before: # end delete
+
+Accept a MR:
+
+.. literalinclude:: mrs.py
+   :start-after: # merge
+   :end-before: # end merge
+
+Cancel a MR when the build succeeds:
+
+.. literalinclude:: mrs.py
+   :start-after: # cancel
+   :end-before: # end cancel
+
+List issues that will close on merge:
+
+.. literalinclude:: mrs.py
+   :start-after: # issues
+   :end-before: # end issues
+
+Subscribe/unsubscribe a MR:
+
+.. literalinclude:: mrs.py
+   :start-after: # subscribe
+   :end-before: # end subscribe
