docs: groups API documentation

3 files changed, 178 insertions, 0 deletions

diff --git a/docs/api-objects.rst b/docs/api-objects.rst
index 1212fb6..8ae7f33 100644
--- a/docs/api-objects.rst
+++ b/docs/api-objects.rst
@@ -6,6 +6,7 @@ API objects manipulation
 
    gl_objects/branches
    gl_objects/builds
+   gl_objects/groups
    gl_objects/projects
    gl_objects/runners
    gl_objects/users
diff --git a/docs/gl_objects/groups.py b/docs/gl_objects/groups.py
new file mode 100644
index 0000000..913c934
--- /dev/null
+++ b/docs/gl_objects/groups.py
@@ -0,0 +1,66 @@
+# list
+groups = gl.groups.list()
+# end list
+
+# search
+groups = gl.groups.search('group')
+# end search
+
+# get
+group = gl.groups.get(group_id)
+# end get
+
+# projects list
+projects = group.projects.list()
+# or
+projects = gl.group_projects.list(group_id)
+# end projects list
+
+# create
+group = gl.groups.create({'name': 'group1', 'path': 'group1'})
+# end create
+
+# update
+group.description = 'My awesome group'
+group.save()
+# end update
+
+# delete
+gl.group.delete(group_id)
+# or
+group.delete()
+# end delete
+
+# member list
+members = gl.group_members.list(group_id=1)
+# or
+members = group.members.list()
+# end member list
+
+# member get
+members = gl.group_members.get(member_id)
+# or
+members = group.members.get(member_id)
+# end member get
+
+# member create
+member = gl.group_members.create({'user_id': user_id,
+                                  'access_level': Group.GUEST_ACCESS},
+                                 group_id=1)
+# or
+member = group.members.create({'user_id': user_id,
+                               'access_level': Group.GUEST_ACCESS})
+# end member create
+
+# member update
+member.access_level = Group.DEVELOPER_ACCESS
+member.save()
+# end member update
+
+# member delete
+gl.group_members.delete(member_id, group_id=1)
+# or
+group.members.delete(member_id)
+# or
+member.delete()
+# end member delete
diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst
new file mode 100644
index 0000000..b2c0ed8
--- /dev/null
+++ b/docs/gl_objects/groups.rst
@@ -0,0 +1,111 @@
+######
+Groups
+######
+
+Groups
+======
+
+Use :class:`~gitlab.objects.Group` objects to manipulate groups. The
+:attr:`gitlab.Gitlab.groups` manager object provides helper functions.
+
+Examples
+--------
+
+List the groups:
+
+.. literalinclude:: groups.py
+   :start-after: # list
+   :end-before: # end list
+
+Search groups:
+
+.. literalinclude:: groups.py
+   :start-after: # search
+   :end-before: # end search
+
+Get a group's detail:
+
+.. literalinclude:: groups.py
+   :start-after: # get
+   :end-before: # end get
+
+List a group's projects:
+
+.. literalinclude:: groups.py
+   :start-after: # projects list
+   :end-before: # end projects list
+
+You can filter and sort the result using the following parameters:
+
+* ``archived``: limit by archived status
+* ``visibility``: limit by visibility. Allowed values are ``public``,
+  ``internal`` and ``private``
+* ``search``: limit to groups matching the given value
+* ``order_by``: sort by criteria. Allowed values are ``id``, ``name``, ``path``,
+  ``created_at``, ``updated_at`` and ``last_activity_at``
+* ``sort``: sort order: ``asc`` or ``desc``
+* ``ci_enabled_first``: return CI enabled groups first
+
+Create a group:
+
+.. literalinclude:: groups.py
+   :start-after: # create
+   :end-before: # end create
+
+Update a group:
+
+.. literalinclude:: groups.py
+   :start-after: # update
+   :end-before: # end update
+
+Remove a group:
+
+.. literalinclude:: groups.py
+   :start-after: # delete
+   :end-before: # end delete
+
+Group members
+=============
+
+Use :class:`~gitlab.objects.GroupMember` objects to manipulate groups. The
+:attr:`gitlab.Gitlab.group_members` and :attr:`Group.members
+<gitlab.objects.Group.members>` manager objects provide helper functions.
+
+The following :class:`~gitlab.objects.Group` attributes define the supported
+access levels:
+
+* ``GUEST_ACCESS = 10``
+* ``REPORTER_ACCESS = 20``
+* ``DEVELOPER_ACCESS = 30``
+* ``MASTER_ACCESS = 40``
+* ``OWNER_ACCESS = 50``
+
+List group members:
+
+.. literalinclude:: groups.py
+   :start-after: # member list
+   :end-before: # end member list
+
+Get a group member:
+
+.. literalinclude:: groups.py
+   :start-after: # member get
+   :end-before: # end member get
+
+Add a member to the group:
+
+.. literalinclude:: groups.py
+   :start-after: # member create
+   :end-before: # end member create
+
+Update a member (change the access level):
+
+.. literalinclude:: groups.py
+   :start-after: # member update
+   :end-before: # end member update
+
+Remove a member from the group:
+
+.. literalinclude:: groups.py
+   :start-after: # member delete
+   :end-before: # end member delete