From fbd2010e09f0412ea52cd16bb26cf988836bc03f Mon Sep 17 00:00:00 2001 From: Gauvain Pocentek Date: Tue, 29 May 2018 06:42:16 +0200 Subject: Add support for group boards --- docs/gl_objects/boards.rst | 95 +++++++++++++++++++++++++++++++++++ docs/gl_objects/dicussions.rst | 107 ---------------------------------------- docs/gl_objects/discussions.rst | 107 ++++++++++++++++++++++++++++++++++++++++ docs/gl_objects/projects.rst | 72 --------------------------- 4 files changed, 202 insertions(+), 179 deletions(-) create mode 100644 docs/gl_objects/boards.rst delete mode 100644 docs/gl_objects/dicussions.rst create mode 100644 docs/gl_objects/discussions.rst (limited to 'docs/gl_objects') diff --git a/docs/gl_objects/boards.rst b/docs/gl_objects/boards.rst new file mode 100644 index 0000000..0099371 --- /dev/null +++ b/docs/gl_objects/boards.rst @@ -0,0 +1,95 @@ +############ +Issue boards +############ + +Boards +====== + +Boards are a visual representation of existing issues for a project or a group. +Issues can be moved from one list to the other to track progress and help with +priorities. + +Reference +--------- + +* v4 API: + + + :class:`gitlab.v4.objects.ProjectBoard` + + :class:`gitlab.v4.objects.ProjectBoardManager` + + :attr:`gitlab.v4.objects.Project.boards` + + :class:`gitlab.v4.objects.GroupBoard` + + :class:`gitlab.v4.objects.GroupBoardManager` + + :attr:`gitlab.v4.objects.Group.boards` + +* GitLab API: + + + https://docs.gitlab.com/ce/api/boards.html + + https://docs.gitlab.com/ce/api/group_boards.html + +Examples +-------- + +Get the list of existing boards for a project or a group:: + + # item is a Project or a Group + boards = item.boards.list() + +Get a single board for a project or a group:: + + board = group.boards.get(board_id) + +.. note:: + + Boards cannot be created using the API, they need to be created using the + UI. + +Board lists +=========== + +Boards are made of lists of issues. Each list is associated to a label, and +issues tagged with this label automatically belong to the list. + +Reference +--------- + +* v4 API: + + + :class:`gitlab.v4.objects.ProjectBoardList` + + :class:`gitlab.v4.objects.ProjectBoardListManager` + + :attr:`gitlab.v4.objects.ProjectBoard.lists` + + :class:`gitlab.v4.objects.GroupBoardList` + + :class:`gitlab.v4.objects.GroupBoardListManager` + + :attr:`gitlab.v4.objects.GroupBoard.lists` + +* GitLab API: + + + https://docs.gitlab.com/ce/api/boards.html + + https://docs.gitlab.com/ce/api/group_boards.html + +Examples +-------- + +List the issue lists for a board:: + + b_lists = board.lists.list() + +Get a single list:: + + b_list = board.lists.get(list_id) + +Create a new list:: + + # First get a ProjectLabel + label = get_or_create_label() + # Then use its ID to create the new board list + b_list = board.lists.create({'label_id': label.id}) + +Change a list position. The first list is at position 0. Moving a list will +set it at the given position and move the following lists up a position:: + + b_list.position = 2 + b_list.save() + +Delete a list:: + + b_list.delete() diff --git a/docs/gl_objects/dicussions.rst b/docs/gl_objects/dicussions.rst deleted file mode 100644 index 7673b7c..0000000 --- a/docs/gl_objects/dicussions.rst +++ /dev/null @@ -1,107 +0,0 @@ -########### -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() 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() diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst index 1abb82c..b02cdd5 100644 --- a/docs/gl_objects/projects.rst +++ b/docs/gl_objects/projects.rst @@ -565,78 +565,6 @@ Disable a service:: service.delete() -Issue boards -============ - -Boards are a visual representation of existing issues for a project. Issues can -be moved from one list to the other to track progress and help with -priorities. - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBoard` - + :class:`gitlab.v4.objects.ProjectBoardManager` - + :attr:`gitlab.v4.objects.Project.boards` - -* GitLab API: https://docs.gitlab.com/ce/api/boards.html - -Examples --------- - -Get the list of existing boards for a project:: - - boards = project.boards.list() - -Get a single board for a project:: - - board = project.boards.get(board_id) - -Board lists -=========== - -Reference ---------- - -* v4 API: - - + :class:`gitlab.v4.objects.ProjectBoardList` - + :class:`gitlab.v4.objects.ProjectBoardListManager` - + :attr:`gitlab.v4.objects.Project.board_lists` - -* GitLab API: https://docs.gitlab.com/ce/api/boards.html - -Examples --------- - -List the issue lists for a board:: - - b_lists = board.lists.list() - -Get a single list:: - - b_list = board.lists.get(list_id) - -Create a new list:: - - # First get a ProjectLabel - label = get_or_create_label() - # Then use its ID to create the new board list - b_list = board.lists.create({'label_id': label.id}) - -Change a list position. The first list is at position 0. Moving a list will -set it at the given position and move the following lists up a position:: - - b_list.position = 2 - b_list.save() - -Delete a list:: - - b_list.delete() - - File uploads ============ -- cgit v1.2.1