12 files changed, 231 insertions, 26 deletions
diff --git a/docs/gl_objects/access_requests.rst b/docs/gl_objects/access_requests.rst
index 9a147c1..e890ce0 100644
--- a/docs/gl_objects/access_requests.rst
+++ b/docs/gl_objects/access_requests.rst
@@ -10,7 +10,7 @@ following constants are provided to represent the access levels:
 * ``gitlab.GUEST_ACCESS``: ``10``
 * ``gitlab.REPORTER_ACCESS``: ``20``
 * ``gitlab.DEVELOPER_ACCESS``: ``30``
-* ``gitlab.MASTER_ACCESS``: ``40``
+* ``gitlab.MAINTAINER_ACCESS``: ``40``
 * ``gitlab.OWNER_ACCESS``: ``50``
 
 References
@@ -43,7 +43,7 @@ Create an access request::
 Approve an access request::
 
     ar.approve()  # defaults to DEVELOPER level
-    ar.approve(access_level=gitlab.MASTER_ACCESS)  # explicitly set access level
+    ar.approve(access_level=gitlab.MAINTAINER_ACCESS)  # explicitly set access level
 
 Deny (delete) an access request::
 
diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst
index 51e7496..ee45090 100644
--- a/docs/gl_objects/builds.rst
+++ b/docs/gl_objects/builds.rst
@@ -141,6 +141,13 @@ Delete a schedule::
 
     sched.delete()
 
+List schedule variables::
+
+    # note: you need to use get() to retrieve the schedule variables. The
+    # attribute is not present in the response of a list() call
+    sched = projects.pipelineschedules.get(schedule_id)
+    vars = sched.attributes['variables']
+
 Create a schedule variable::
 
     var = sched.variables.create({'key': 'foo', 'value': 'bar'})
diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst
index f662fcb..9f48c98 100644
--- a/docs/gl_objects/commits.rst
+++ b/docs/gl_objects/commits.rst
@@ -27,6 +27,14 @@ results::
     commits = project.commits.list(ref_name='my_branch')
     commits = project.commits.list(since='2016-01-01T00:00:00Z')
 
+.. note::
+
+   The available ``all`` listing argument conflicts with the python-gitlab
+   argument. Use ``query_parameters`` to avoid the conflict::
+
+       commits = project.commits.list(all=True,
+                                      query_parameters={'ref_name': 'my_branch'})
+
 Create a commit::
 
     # See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
@@ -85,7 +93,7 @@ Reference
 
   + :class:`gitlab.v4.objects.ProjectCommitComment`
   + :class:`gitlab.v4.objects.ProjectCommitCommentManager`
-  + :attr:`gitlab.v4.objects.Commit.comments`
+  + :attr:`gitlab.v4.objects.ProjectCommit.comments`
 
 * GitLab API: https://docs.gitlab.com/ce/api/commits.html
 
@@ -116,7 +124,7 @@ Reference
 
   + :class:`gitlab.v4.objects.ProjectCommitStatus`
   + :class:`gitlab.v4.objects.ProjectCommitStatusManager`
-  + :attr:`gitlab.v4.objects.Commit.statuses`
+  + :attr:`gitlab.v4.objects.ProjectCommit.statuses`
 
 * GitLab API: https://docs.gitlab.com/ce/api/commits.html
 
diff --git a/docs/gl_objects/discussions.rst b/docs/gl_objects/discussions.rst
index 7673b7c..444d883 100644
--- a/docs/gl_objects/discussions.rst
+++ b/docs/gl_objects/discussions.rst
@@ -48,7 +48,7 @@ List the discussions for a resource (issue, merge request, snippet or commit)::
 
 Get a single discussion::
 
-    discussion = resource.discussion.get(discussion_id)
+    discussion = resource.discussions.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::
@@ -68,7 +68,7 @@ You can add notes to existing discussions::
 
 You can get and update a single note using the ``*DiscussionNote`` resources::
 
-    discussion = resource.discussion.get(discussion_id)
+    discussion = resource.discussions.get(discussion_id)
     # Get the latest note's id
     note_id = discussion.attributes['note'][-1]['id']
     last_note = discussion.notes.get(note_id)
@@ -77,7 +77,7 @@ You can get and update a single note using the ``*DiscussionNote`` resources::
 
 Create a new discussion::
 
-    discussion = resource.discussion.create({'body': 'First comment of discussion'})
+    discussion = resource.discussions.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::
diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst
index 5ef5469..7fcf980 100644
--- a/docs/gl_objects/groups.rst
+++ b/docs/gl_objects/groups.rst
@@ -31,6 +31,15 @@ List a group's projects::
 
     projects = group.projects.list()
 
+.. note::
+
+   ``GroupProject`` objects returned by this API call are very limited, and do
+   not provide all the features of ``Project`` objects. If you need to
+   manipulate projects, create a new ``Project`` object::
+
+       first_group_project = group.projects.list()[0]
+       manageable_project = gl.projects.get(first_group_project.id, lazy=True)
+
 You can filter and sort the result using the following parameters:
 
 * ``archived``: limit by archived status
@@ -53,7 +62,7 @@ Update a group::
 
 Remove a group::
 
-    gl.group.delete(group_id)
+    gl.groups.delete(group_id)
     # or
     group.delete()
 
@@ -76,11 +85,14 @@ List the subgroups for a group::
 
     subgroups = group.subgroups.list()
 
-    # The GroupSubgroup objects don't expose the same API as the Group
-    # objects. If you need to manipulate a subgroup as a group, create a new
-    # Group object:
-    real_group = gl.groups.get(subgroup_id, lazy=True)
-    real_group.issues.list()
+.. note::
+
+    The ``GroupSubgroup`` objects don't expose the same API as the ``Group``
+    objects.  If you need to manipulate a subgroup as a group, create a new
+    ``Group`` object::
+
+        real_group = gl.groups.get(subgroup_id, lazy=True)
+        real_group.issues.list()
 
 Group custom attributes
 =======================
@@ -130,7 +142,7 @@ The following constants define the supported access levels:
 * ``gitlab.GUEST_ACCESS = 10``
 * ``gitlab.REPORTER_ACCESS = 20``
 * ``gitlab.DEVELOPER_ACCESS = 30``
-* ``gitlab.MASTER_ACCESS = 40``
+* ``gitlab.MAINTAINER_ACCESS = 40``
 * ``gitlab.OWNER_ACCESS = 50``
 
 Reference
@@ -152,6 +164,11 @@ List group members::
 
     members = group.members.list()
 
+List the group members recursively (including inherited members through
+ancestor groups)::
+
+    members = group.members.all(all=True)
+
 Get a group member::
 
     members = group.members.get(member_id)
diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst
index 7abaa78..12df90b 100644
--- a/docs/gl_objects/issues.rst
+++ b/docs/gl_objects/issues.rst
@@ -1,3 +1,5 @@
+.. _issues_examples:
+
 ######
 Issues
 ######
@@ -30,6 +32,17 @@ Use the ``state`` and ``label`` parameters to filter the results. Use the
     closed_issues = gl.issues.list(state='closed')
     tagged_issues = gl.issues.list(labels=['foo', 'bar'])
 
+.. note::
+
+   It is not possible to edit or delete Issue objects. You need to create a
+   ProjectIssue object to perform changes::
+
+       issue = gl.issues.list()[0]
+       project = gl.projects.get(issue.project_id, lazy=True)
+       editable_issue = project.issues.get(issue.iid, lazy=True)
+       editable_issue.title = updated_title
+       editable_issue.save()
+
 Group issues
 ============
 
@@ -55,6 +68,17 @@ List the group issues::
     # Order using the order_by and sort parameters
     issues = group.issues.list(order_by='created_at', sort='desc')
 
+.. note::
+
+   It is not possible to edit or delete GroupIssue objects. You need to create
+   a ProjectIssue object to perform changes::
+
+       issue = group.issues.list()[0]
+       project = gl.projects.get(issue.project_id, lazy=True)
+       editable_issue = project.issues.get(issue.iid, lazy=True)
+       editable_issue.title = updated_title
+       editable_issue.save()
+
 Project issues
 ==============
 
diff --git a/docs/gl_objects/labels.rst b/docs/gl_objects/labels.rst
index 1c98971..a4667aa 100644
--- a/docs/gl_objects/labels.rst
+++ b/docs/gl_objects/labels.rst
@@ -2,6 +2,9 @@
 Labels
 ######
 
+Project labels
+==============
+
 Reference
 ---------
 
@@ -48,3 +51,39 @@ Manage labels in issues and merge requests::
                              'labels': ['foo']})
     issue.labels.append('bar')
     issue.save()
+
+Label events
+============
+
+Resource label events keep track about who, when, and which label was added or
+removed to an issuable.
+
+Group epic label events are only available in the EE edition.
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEvent`
+  + :class:`gitlab.v4.objects.ProjectIssueResourceLabelEventManager`
+  + :attr:`gitlab.v4.objects.ProjectIssue.resourcelabelevents`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEvent`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestResourceLabelEventManager`
+  + :attr:`gitlab.v4.objects.ProjectMergeRequest.resourcelabelevents`
+  + :class:`gitlab.v4.objects.GroupEpicResourceLabelEvent`
+  + :class:`gitlab.v4.objects.GroupEpicResourceLabelEventManager`
+  + :attr:`gitlab.v4.objects.GroupEpic.resourcelabelevents`
+
+* GitLab API: https://docs.gitlab.com/ee/api/resource_label_events.html
+
+Examples
+--------
+
+Get the events for a resource (issue, merge request or epic)::
+
+    events = resource.resourcelabelevents.list()
+
+Get a specific event for a resource::
+
+    event = resource.resourcelabelevents.get(event_id)
diff --git a/docs/gl_objects/milestones.rst b/docs/gl_objects/milestones.rst
index 0d3f576..f24e13f 100644
--- a/docs/gl_objects/milestones.rst
+++ b/docs/gl_objects/milestones.rst
@@ -30,7 +30,7 @@ List the milestones for a project or a group::
 
 You can filter the list using the following parameters:
 
-* ``iid``: unique ID of the milestone for the project
+* ``iids``: unique IDs of milestones for the project
 * ``state``: either ``active`` or ``closed``
 * ``search``: to search using a string
 
diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst
index ca9b864..b3b5e07 100644
--- a/docs/gl_objects/mrs.rst
+++ b/docs/gl_objects/mrs.rst
@@ -1,3 +1,5 @@
+.. _merge_requests_examples:
+
 ##############
 Merge requests
 ##############
@@ -5,6 +7,53 @@ Merge requests
 You can use merge requests to notify a project that a branch is ready for
 merging. The owner of the target projet can accept the merge request.
 
+Merge requests are linked to projects, but they can be listed globally or for
+groups.
+
+Group and global listing
+========================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.GroupMergeRequest`
+  + :class:`gitlab.v4.objects.GroupMergeRequestManager`
+  + :attr:`gitlab.v4.objects.Group.mergerequests`
+  + :class:`gitlab.v4.objects.MergeRequest`
+  + :class:`gitlab.v4.objects.MergeRequestManager`
+  + :attr:`gitlab.Gtilab.mergerequests`
+
+* GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html
+
+Examples
+--------
+
+List the merge requests available on the GitLab server::
+
+    mrs = gl.mergerequests.list()
+
+List the merge requests for a group::
+
+    group = gl.groups.get('mygroup')
+    mrs = group.mergerequests.list()
+
+.. note::
+
+   It is not possible to edit or delete ``MergeRequest`` and
+   ``GroupMergeRequest`` objects. You need to create a ``ProjectMergeRequest``
+   object to apply changes::
+
+       mr = group.mergerequests.list()[0]
+       project = gl.projects.get(mr.project_id, lazy=True)
+       editable_mr = project.mergerequests.get(mr.iid, lazy=True)
+       editable_mr.title = updated_title
+       editable_mr.save()
+
+Project merge requests
+======================
+
 Reference
 ---------
 
@@ -74,6 +123,14 @@ List commits of a MR::
 
     commits = mr.commits()
 
+List the changes of a MR::
+
+    changes = mr.changes()
+
+List the pipelines for a MR::
+
+    pipelines = mr.pipelines()
+
 List issues that will close on merge::
 
     mr.closes_issues()
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index 3950862..a00aae0 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -45,10 +45,10 @@ Results can also be sorted using the following parameters:
     projects = gl.projects.list(visibility='public')
 
     # List owned projects
-    projects = gl.projects.owned()
+    projects = gl.projects.list(owned=True)
 
     # List starred projects
-    projects = gl.projects.starred()
+    projects = gl.projects.list(starred=True)
 
     # Search projects
     projects = gl.projects.list(search='keyword')
@@ -95,6 +95,10 @@ Fork a project::
     # fork to a specific namespace
     fork = project.forks.create({'namespace': 'myteam'})
 
+Get a list of forks for the project::
+
+    forks = project.forks.list()
+
 Create/delete a fork relation between projects (requires admin permissions)::
 
     project.create_fork_relation(source_project.id)
@@ -243,7 +247,7 @@ generated by GitLab you need to:
 
 Import the project::
 
-    gl.projects.import_project(open('/tmp/export.tgz', 'rb'), 'my_new_project')
+    ouput = gl.projects.import_project(open('/tmp/export.tgz', 'rb'), 'my_new_project')
     # Get a ProjectImport object to track the import status
     project_import = gl.projects.get(output['id'], lazy=True).imports.get()
     while project_import.import_status != 'finished':
@@ -288,7 +292,7 @@ Delete a custom attribute for a project::
 
 Search projects by custom attribute::
 
-    project.customattributes.set('type': 'internal')
+    project.customattributes.set('type', 'internal')
     gl.projects.list(custom_attributes={'type': 'internal'})
 
 Project files
@@ -474,6 +478,11 @@ List the project members::
 
     members = project.members.list()
 
+List the project members recursively (including inherited members through
+ancestor groups)::
+
+    members = project.members.all(all=True)
+
 Search project members matching a query string::
 
     members = project.members.list(query='bar')
@@ -489,7 +498,7 @@ Add a project member::
 
 Modify a project member (change the access level)::
 
-    member.access_level = gitlab.MASTER_ACCESS
+    member.access_level = gitlab.MAINTAINER_ACCESS
     member.save()
 
 Remove a member from the project team::
@@ -653,3 +662,36 @@ Edit project push rules::
 Delete project push rules::
 
     pr.delete()
+
+Project protected tags
+======================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectProtectedTag`
+  + :class:`gitlab.v4.objects.ProjectProtectedTagManager`
+  + :attr:`gitlab.v4.objects.Project.protectedtags`
+
+* GitLab API: https://docs.gitlab.com/ce/api/protected_tags.html
+
+Examples
+---------
+
+Get a list of protected tags from a project::
+
+    protected_tags = project.protectedtags.list()
+
+Get a single protected tag or wildcard protected tag::
+
+    protected_tag = project.protectedtags.get('v*')
+
+Protect a single repository tag or several project repository tags using a wildcard protected tag::
+
+    project.protectedtags.create({'name': 'v*', 'create_access_level': '40'})
+
+Unprotect the given protected tag or wildcard protected tag.::
+
+    protected_tag.delete()
diff --git a/docs/gl_objects/protected_branches.rst b/docs/gl_objects/protected_branches.rst
index bd2b22b..3498aa5 100644
--- a/docs/gl_objects/protected_branches.rst
+++ b/docs/gl_objects/protected_branches.rst
@@ -32,7 +32,16 @@ Create a protected branch::
     p_branch = project.protectedbranches.create({
         'name': '*-stable',
         'merge_access_level': gitlab.DEVELOPER_ACCESS,
-        'push_access_level': gitlab.MASTER_ACCESS
+        'push_access_level': gitlab.MAINTAINER_ACCESS
+    })
+
+Create a protected branch with more granular access control::
+
+    p_branch = project.protectedbranches.create({
+        'name': '*-stable',
+        'allowed_to_push': [{"user_id": 99}, {"user_id": 98}],
+        'allowed_to_merge': [{"group_id": 653}],
+        'allowed_to_unprotect': [{"access_level": gitlab.MAINTAINER_ACCESS}]
     })
 
 Delete a protected branch::
diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst
index 3b9c040..e66ef3a 100644
--- a/docs/gl_objects/users.rst
+++ b/docs/gl_objects/users.rst
@@ -112,7 +112,7 @@ Delete a custom attribute for a user::
 
 Search users by custom attribute::
 
-    user.customattributes.set('role': 'QA')
+    user.customattributes.set('role', 'QA')
     gl.users.list(custom_attributes={'role': 'QA'})
 
 User impersonation tokens
@@ -190,7 +190,7 @@ are admin.
 
 * GitLab API: https://docs.gitlab.com/ce/api/users.html#list-all-gpg-keys
 
-Exemples
+Examples
 --------
 
 List GPG keys for a user::
@@ -232,7 +232,7 @@ are admin.
 
 * GitLab API: https://docs.gitlab.com/ce/api/users.html#list-ssh-keys
 
-Exemples
+Examples
 --------
 
 List SSH keys for a user::
@@ -270,7 +270,7 @@ are admin.
 
 * GitLab API: https://docs.gitlab.com/ce/api/users.html#list-emails
 
-Exemples
+Examples
 --------
 
 List emails for a user::
@@ -312,4 +312,6 @@ Examples
 
 Get the users activities::
 
-    activities = gl.user_activities.list(all=True, as_list=False)
+    activities = gl.user_activities.list(
+        query_parameters={'from': '2018-07-01'},
+        all=True, as_list=False)