[docs] Add/updates notes about read-only objects

Gauvain Pocentek · Gauvain Pocentek · commit 80a68f925842 · 2018-08-24T11:17:21.000+02:00
MR and issues attached to the root API or groups are not editable.
Provide notes describing how to manage this.
diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst
@@ -30,6 +30,17 @@ Use the ``state`` and ``label`` parameters to filter the results. Use the
     closed_issues = gl.issues.list(state='closed')
     tagged_issues = gl.issues.list(labels=['foo', 'bar'])
 
+.. note::
+
+   It is not possible to edit or delete Issue objects. You need to create a
+   ProjectIssue object to perform changes::
+
+       issue = gl.issues.list()[0]
+       project = gl.projects.get(issue.project_id, lazy=True)
+       editable_issue = project.issues.get(issue.iid, lazy=True)
+       editable_issue.title = updated_title
+       editable_issue.save()
+
 Group issues
 ============
 
@@ -55,6 +66,17 @@ List the group issues::
     # Order using the order_by and sort parameters
     issues = group.issues.list(order_by='created_at', sort='desc')
 
+.. note::
+
+   It is not possible to edit or delete GroupIssue objects. You need to create
+   a ProjectIssue object to perform changes::
+
+       issue = group.issues.list()[0]
+       project = gl.projects.get(issue.project_id, lazy=True)
+       editable_issue = project.issues.get(issue.iid, lazy=True)
+       editable_issue.title = updated_title
+       editable_issue.save()
+
 Project issues
 ==============
 
diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst
@@ -37,12 +37,17 @@ List the merge requests for a group::
     group = gl.groups.get('mygroup')
     mrs = group.mergerequests.list()
 
-To edit or delete a merge request, create a ``ProjectMergeRequest`` object
-first::
+.. note::
 
-    mr = group.mergerequests.list()[0]  # pick the first MR
-    project = gl.projects.get(mr.project_id, lazy=True)
-    editable_mr = project.mergerequests.get(mr.iid)
+   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
 ======================
