1 files changed, 107 insertions, 0 deletions
diff --git a/docs/gl_objects/discussions.rst b/docs/gl_objects/discussions.rst
new file mode 100644
index 0000000..7673b7c
--- /dev/null
+++ b/docs/gl_objects/discussions.rst
@@ -0,0 +1,107 @@
+###########
+Discussions
+###########
+
+Discussions organize the notes in threads. See the :ref:`project-notes` chapter
+for more information about notes.
+
+Discussions are available for project issues, merge requests, snippets and
+commits.
+
+Reference
+=========
+
+* v4 API:
+
+  Issues:
+
+  + :class:`gitlab.v4.objects.ProjectIssueDiscussion`
+  + :class:`gitlab.v4.objects.ProjectIssueDiscussionManager`
+  + :class:`gitlab.v4.objects.ProjectIssueDiscussionNote`
+  + :class:`gitlab.v4.objects.ProjectIssueDiscussionNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectIssue.notes`
+
+  MergeRequests:
+
+  + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussion`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionManager`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNote`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes`
+
+  Snippets:
+
+  + :class:`gitlab.v4.objects.ProjectSnippetDiscussion`
+  + :class:`gitlab.v4.objects.ProjectSnippetDiscussionManager`
+  + :class:`gitlab.v4.objects.ProjectSnippetDiscussionNote`
+  + :class:`gitlab.v4.objects.ProjectSnippetDiscussionNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectSnippet.notes`
+
+* GitLab API: https://docs.gitlab.com/ce/api/discussions.html
+
+Examples
+========
+
+List the discussions for a resource (issue, merge request, snippet or commit)::
+
+    discussions = resource.discussions.list()
+
+Get a single discussion::
+
+    discussion = resource.discussion.get(discussion_id)
+
+You can access the individual notes in the discussion through the ``notes``
+attribute. It holds a list of notes in chronological order::
+
+    # ``resource.notes`` is a DiscussionNoteManager, so we need to get the
+    # object notes using ``attributes``
+    for note in discussion.attributes['notes']:
+        print(note['body'])
+
+.. note::
+
+   The notes are dicts, not objects.
+
+You can add notes to existing discussions::
+
+    new_note = discussion.notes.create({'body': 'Episode IV: A new note'})
+
+You can get and update a single note using the ``*DiscussionNote`` resources::
+
+    discussion = resource.discussion.get(discussion_id)
+    # Get the latest note's id
+    note_id = discussion.attributes['note'][-1]['id']
+    last_note = discussion.notes.get(note_id)
+    last_note.body = 'Updated comment'
+    last_note.save()
+
+Create a new discussion::
+
+    discussion = resource.discussion.create({'body': 'First comment of discussion'})
+
+You can comment on merge requests and commit diffs. Provide the ``position``
+dict to define where the comment should appear in the diff::
+
+    mr_diff = mr.diffs.get(diff_id)
+    mr.discussions.create({'body': 'Note content',
+                           'position': {
+                               'base_sha': mr_diff.base_commit_sha,
+                               'start_sha': mr_diff.start_commit_sha,
+                               'head_sha': mr_diff.head_commit_sha,
+                               'position_type': 'text',
+                               'new_line': 1,
+                               'old_path': 'README.rst',
+                               'new_path': 'README.rst'}
+                           })
+
+Resolve / unresolve a merge request discussion::
+
+    mr_d = mr.discussions.get(d_id)
+    mr_d.resolved = True  # True to resolve, False to unresolve
+    mr_d.save()
+
+Delete a comment::
+
+    discussions.notes.delete(note_id)
+    # or
+    note.delete()