1 files changed, 95 insertions, 0 deletions
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()