[docs] Move notes examples in their own file

Fixes #472
python-gitlab · Mar 28, 2018 · f980707 · f980707
1 parent f09089b
commit f980707
Show file tree

Hide file tree

Showing 4 changed files with 92 additions and 120 deletions.
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -22,8 +22,9 @@ API examples
    gl_objects/labels
    gl_objects/notifications
    gl_objects/mrs
-   gl_objects/namespaces
    gl_objects/milestones
+   gl_objects/namespaces
+   gl_objects/notes
    gl_objects/pagesdomains
    gl_objects/projects
    gl_objects/runners

diff --git a/docs/gl_objects/notes.rst b/docs/gl_objects/notes.rst
@@ -0,0 +1,89 @@
+.. _project-notes:
+
+#####
+Notes
+#####
+
+You can manipulate notes (comments) on project issues, merge requests and
+snippets.
+
+Reference
+---------
+
+* v4 API:
+
+  Issues:
+
+  + :class:`gitlab.v4.objects.ProjectIssueNote`
+  + :class:`gitlab.v4.objects.ProjectIssueNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectIssue.notes`
+
+  MergeRequests:
+
+  + :class:`gitlab.v4.objects.ProjectMergeRequestNote`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes`
+
+  Snippets:
+
+  + :class:`gitlab.v4.objects.ProjectSnippetNote`
+  + :class:`gitlab.v4.objects.ProjectSnippetNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectSnippet.notes`
+
+* v3 API:
+
+  Issues:
+
+  + :class:`gitlab.v3.objects.ProjectIssueNote`
+  + :class:`gitlab.v3.objects.ProjectIssueNoteManager`
+  + :attr:`gitlab.v3.objects.ProjectIssue.notes`
+  + :attr:`gitlab.v3.objects.Project.issue_notes`
+  + :attr:`gitlab.Gitlab.project_issue_notes`
+
+  MergeRequests:
+
+  + :class:`gitlab.v3.objects.ProjectMergeRequestNote`
+  + :class:`gitlab.v3.objects.ProjectMergeRequestNoteManager`
+  + :attr:`gitlab.v3.objects.ProjectMergeRequest.notes`
+  + :attr:`gitlab.v3.objects.Project.mergerequest_notes`
+  + :attr:`gitlab.Gitlab.project_mergerequest_notes`
+
+  Snippets:
+
+  + :class:`gitlab.v3.objects.ProjectSnippetNote`
+  + :class:`gitlab.v3.objects.ProjectSnippetNoteManager`
+  + :attr:`gitlab.v3.objects.ProjectSnippet.notes`
+  + :attr:`gitlab.v3.objects.Project.snippet_notes`
+  + :attr:`gitlab.Gitlab.project_snippet_notes`
+
+* GitLab API: https://docs.gitlab.com/ce/api/notes.html
+
+Examples
+--------
+
+List the notes for a resource::
+
+    i_notes = issue.notes.list()
+    mr_notes = mr.notes.list()
+    s_notes = snippet.notes.list()
+
+Get a note for a resource::
+
+    i_note = issue.notes.get(note_id)
+    mr_note = mr.notes.get(note_id)
+    s_note = snippet.notes.get(note_id)
+
+Create a note for a resource::
+
+    i_note = issue.notes.create({'body': 'note content'})
+    mr_note = mr.notes.create({'body': 'note content'})
+    s_note = snippet.notes.create({'body': 'note content'})
+
+Update a note for a resource::
+
+    note.body = 'updated note content'
+    note.save()
+
+Delete a note for a resource::
+
+    note.delete()
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
@@ -276,33 +276,6 @@
 snippet.delete()
 # end snippets delete
 
-# notes list
-i_notes = issue.notes.list()
-mr_notes = mr.notes.list()
-s_notes = snippet.notes.list()
-# end notes list
-
-# notes get
-i_note = issue.notes.get(note_id)
-mr_note = mr.notes.get(note_id)
-s_note = snippet.notes.get(note_id)
-# end notes get
-
-# notes create
-i_note = issue.notes.create({'body': 'note content'})
-mr_note = mr.notes.create({'body': 'note content'})
-s_note = snippet.notes.create({'body': 'note content'})
-# end notes create
-
-# notes update
-note.body = 'updated note content'
-note.save()
-# end notes update
-
-# notes delete
-note.delete()
-# end notes delete
-
 # service get
 # For v3
 service = project.services.get(service_name='asana', project_id=1)

diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
@@ -391,98 +391,7 @@ Delete a snippet:
 Notes
 =====
 
-You can manipulate notes (comments) on the issues, merge requests and snippets.
-
-* :class:`~gitlab.objects.ProjectIssue` with
-  :class:`~gitlab.objects.ProjectIssueNote`
-* :class:`~gitlab.objects.ProjectMergeRequest` with
-  :class:`~gitlab.objects.ProjectMergeRequestNote`
-* :class:`~gitlab.objects.ProjectSnippet` with
-  :class:`~gitlab.objects.ProjectSnippetNote`
-
-Reference
----------
-
-* v4 API:
-
-  Issues:
-
-  + :class:`gitlab.v4.objects.ProjectIssueNote`
-  + :class:`gitlab.v4.objects.ProjectIssueNoteManager`
-  + :attr:`gitlab.v4.objects.ProjectIssue.notes`
-
-  MergeRequests:
-
-  + :class:`gitlab.v4.objects.ProjectMergeRequestNote`
-  + :class:`gitlab.v4.objects.ProjectMergeRequestNoteManager`
-  + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes`
-
-  Snippets:
-
-  + :class:`gitlab.v4.objects.ProjectSnippetNote`
-  + :class:`gitlab.v4.objects.ProjectSnippetNoteManager`
-  + :attr:`gitlab.v4.objects.ProjectSnippet.notes`
-
-* v3 API:
-
-  Issues:
-
-  + :class:`gitlab.v3.objects.ProjectIssueNote`
-  + :class:`gitlab.v3.objects.ProjectIssueNoteManager`
-  + :attr:`gitlab.v3.objects.ProjectIssue.notes`
-  + :attr:`gitlab.v3.objects.Project.issue_notes`
-  + :attr:`gitlab.Gitlab.project_issue_notes`
-
-  MergeRequests:
-
-  + :class:`gitlab.v3.objects.ProjectMergeRequestNote`
-  + :class:`gitlab.v3.objects.ProjectMergeRequestNoteManager`
-  + :attr:`gitlab.v3.objects.ProjectMergeRequest.notes`
-  + :attr:`gitlab.v3.objects.Project.mergerequest_notes`
-  + :attr:`gitlab.Gitlab.project_mergerequest_notes`
-
-  Snippets:
-
-  + :class:`gitlab.v3.objects.ProjectSnippetNote`
-  + :class:`gitlab.v3.objects.ProjectSnippetNoteManager`
-  + :attr:`gitlab.v3.objects.ProjectSnippet.notes`
-  + :attr:`gitlab.v3.objects.Project.snippet_notes`
-  + :attr:`gitlab.Gitlab.project_snippet_notes`
-
-* GitLab API: https://docs.gitlab.com/ce/api/notes.html
-
-Examples
---------
-
-List the notes for a resource:
-
-.. literalinclude:: projects.py
-   :start-after: # notes list
-   :end-before: # end notes list
-
-Get a note for a resource:
-
-.. literalinclude:: projects.py
-   :start-after: # notes get
-   :end-before: # end notes get
-
-Create a note for a resource:
-
-.. literalinclude:: projects.py
-   :start-after: # notes create
-   :end-before: # end notes create
-
-Update a note for a resource:
-
-.. literalinclude:: projects.py
-   :start-after: # notes update
-   :end-before: # end notes update
-
-Delete a note for a resource:
-
-.. literalinclude:: projects.py
-   :start-after: # notes delete
-   :end-before: # end notes delete
+See :ref:`project-notes`.
 
 Project members
 ===============