17 files changed, 322 insertions, 35 deletions
diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index ede2d47..8ab252c 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -2,12 +2,12 @@
 Getting started with the API
 ############################
 
-python-gitlab supports both GitLab v3 and v4 APIs. To use the v3 make sure to
+python-gitlab supports both GitLab v3 and v4 APIs.
 
 .. note::
 
    To use the v3 make sure to install python-gitlab 1.4. Only the v4 API is
-   documented here. See the documentation of earlier version for the v3 API.
+   documented here. See the documentation of earlier versions for the v3 API.
 
 ``gitlab.Gitlab`` class
 =======================
@@ -43,6 +43,11 @@ You can also use configuration files to create ``gitlab.Gitlab`` objects:
 See the :ref:`cli_configuration` section for more information about
 configuration files.
 
+.. warning::
+
+   If the GitLab server you are using redirects requests from http to https,
+   make sure to use the ``https://`` protocol in the URL definition.
+
 Note on password authentication
 -------------------------------
 
@@ -88,7 +93,7 @@ Examples:
 You can list the mandatory and optional attributes for object creation and
 update with the manager's ``get_create_attrs()`` and ``get_update_attrs()``
 methods. They return 2 tuples, the first one is the list of mandatory
-attributes, the second one the list of optional attribute:
+attributes, the second one is the list of optional attribute:
 
 .. code-block:: python
 
@@ -113,6 +118,25 @@ Some objects also provide managers to access related GitLab resources:
    project = gl.projects.get(1)
    issues = project.issues.list()
 
+python-gitlab allows to send any data to the GitLab server when making queries.
+In case of invalid or missing arguments python-gitlab will raise an exception
+with the GitLab server error message:
+
+.. code-block:: python
+
+   >>> gl.projects.list(sort='invalid value')
+   ...
+   GitlabListError: 400: sort does not have a valid value
+
+You can use the ``query_parameters`` argument to send arguments that would
+conflict with python or python-gitlab when using them as kwargs:
+
+.. code-block:: python
+
+   gl.user_activities.list(from='2019-01-01')  ## invalid
+
+   gl.user_activities.list(query_parameters={'from': '2019-01-01'})  # OK
+
 Gitlab Objects
 ==============
 
@@ -187,7 +211,7 @@ parameter to get all the items when using listing methods:
 .. code-block:: python
 
    all_groups = gl.groups.list(all=True)
-   all_owned_projects = gl.projects.owned(all=True)
+   all_owned_projects = gl.projects.list(owned=True, all=True)
 
 You can define the ``per_page`` value globally to avoid passing it to every
 ``list()`` method call:
@@ -206,7 +230,7 @@ through a large number of items:
    for item in items:
        print(item.attributes)
 
-The generator exposes extra listing information as received by the server:
+The generator exposes extra listing information as received from the server:
 
 * ``current_page``: current page number (first page is 1)
 * ``prev_page``: if ``None`` the current page is the first one
@@ -249,7 +273,7 @@ properly closed when you exit a ``with`` block:
 .. warning::
 
    The context manager will also close the custom ``Session`` object you might
-   have used to build a ``Gitlab`` instance.
+   have used to build the ``Gitlab`` instance.
 
 Proxy configuration
 -------------------
@@ -294,7 +318,9 @@ Rate limits
 
 python-gitlab obeys the rate limit of the GitLab server by default.  On
 receiving a 429 response (Too Many Requests), python-gitlab sleeps for the
-amount of time in the Retry-After header that GitLab sends back.
+amount of time in the Retry-After header that GitLab sends back.  If GitLab
+does not return a response with the Retry-After header, python-gitlab will
+perform an exponential backoff.
 
 If you don't want to wait, you can disable the rate-limiting feature, by
 supplying the ``obey_rate_limit`` argument.
@@ -307,6 +333,18 @@ supplying the ``obey_rate_limit`` argument.
    gl = gitlab.gitlab(url, token, api_version=4)
    gl.projects.list(all=True, obey_rate_limit=False)
 
+If you do not disable the rate-limiting feature, you can supply a custom value
+for ``max_retries``; by default, this is set to 10. To retry without bound when
+throttled, you can set this parameter to -1. This parameter is ignored if
+``obey_rate_limit`` is set to ``False``.
+
+.. code-block:: python
+
+   import gitlab
+   import requests
+
+   gl = gitlab.gitlab(url, token, api_version=4)
+   gl.projects.list(all=True, max_retries=12)
 
 .. warning::
 
diff --git a/docs/cli.rst b/docs/cli.rst
index 654c00a..2051d03 100644
--- a/docs/cli.rst
+++ b/docs/cli.rst
@@ -69,7 +69,7 @@ parameters. You can override the values in each GitLab server section.
      - Integer
      - Number of seconds to wait for an answer before failing.
    * - ``api_version``
-     - ``3`` ou ``4``
+     - ``3`` or ``4``
      - The API version to use to make queries. Requires python-gitlab >= 1.3.0.
    * - ``per_page``
      - Integer between 1 and 100
@@ -78,6 +78,11 @@ parameters. You can override the values in each GitLab server section.
 
 You must define the ``url`` in each GitLab server section.
 
+.. warning::
+
+   If the GitLab server you are using redirects requests from http to https,
+   make sure to use the ``https://`` protocol in the ``url`` definition.
+
 Only one of ``private_token`` or ``oauth_token`` should be defined. If neither
 are defined an anonymous request will be sent to the Gitlab server, with very
 limited permissions.
@@ -152,6 +157,11 @@ These options must be defined before the mandatory arguments.
 ``--output``, ``-o``
     Output format. Defaults to a custom format. Can also be ``yaml`` or ``json``.
 
+    **Notice:**
+
+        The `PyYAML package <https://pypi.org/project/PyYAML/>`_ is required to use the yaml output option.
+        You need to install it separately using ``pip install PyYAML``
+
 ``--fields``, ``-f``
     Comma-separated list of fields to display (``yaml`` and ``json`` output
     formats only).  If not used, all the object fields are displayed.
diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000..fe71198
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,33 @@
+###
+FAQ
+###
+
+I cannot edit the merge request / issue I've just retrieved
+    It is likely that you used a ``MergeRequest``, ``GroupMergeRequest``,
+    ``Issue`` or ``GroupIssue`` object. These objects cannot be edited. But you
+    can create a new ``ProjectMergeRequest`` or ``ProjectIssue`` object to
+    apply changes. For example::
+
+        issue = gl.issues.list()[0]
+        project = gl.projects.get(issue.project_id, lazy=True)
+        editable_issue = project.issues.get(issue.iid, lazy=True)
+        # you can now edit the object
+
+    See the :ref:`merge requests example <merge_requests_examples>` and the
+    :ref:`issues examples <issues_examples>`.
+
+How can I clone the repository of a project?
+    python-gitlab doesn't provide an API to clone a project. You have to use a
+    git library or call the ``git`` command.
+
+    The git URI is exposed in the ``ssh_url_to_repo`` attribute of ``Project``
+    objects.
+
+    Example::
+
+        import subprocess
+
+        project = gl.projects.create(data)  # or gl.projects.get(project_id)
+        print(project.attributes)  # displays all the attributes
+        git_url = project.ssh_url_to_repo
+        subprocess.call(['git', 'clone', git_url])
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)
diff --git a/docs/index.rst b/docs/index.rst
index 7805fcf..9c8cfd3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    install
    cli
    api-usage
+   faq
    switching-to-v4
    api-objects
    api/gitlab
diff --git a/docs/switching-to-v4.rst b/docs/switching-to-v4.rst
index ef21060..e6490e3 100644
--- a/docs/switching-to-v4.rst
+++ b/docs/switching-to-v4.rst
@@ -10,7 +10,7 @@ solve some problems with the existing one.
 
 GitLab will stop supporting the v3 API soon, and you should consider switching
 to v4 if you use a recent version of GitLab (>= 9.0), or if you use
-http://gitlab.com.
+https://gitlab.com.
 
 
 Using the v4 API