Update the objects doc/examples for v4

36 files changed, 991 insertions, 464 deletions

diff --git a/docs/gl_objects/access_requests.py b/docs/gl_objects/access_requests.py
index 6497ca1..9df639d 100644
--- a/docs/gl_objects/access_requests.py
+++ b/docs/gl_objects/access_requests.py
@@ -1,23 +1,14 @@
 # list
-p_ars = gl.project_accessrequests.list(project_id=1)
-g_ars = gl.group_accessrequests.list(group_id=1)
-# or
 p_ars = project.accessrequests.list()
 g_ars = group.accessrequests.list()
 # end list
 
 # get
-p_ar = gl.project_accessrequests.get(user_id, project_id=1)
-g_ar = gl.group_accessrequests.get(user_id, group_id=1)
-# or
 p_ar = project.accessrequests.get(user_id)
 g_ar = group.accessrequests.get(user_id)
 # end get
 
 # create
-p_ar = gl.project_accessrequests.create({}, project_id=1)
-g_ar = gl.group_accessrequests.create({}, group_id=1)
-# or
 p_ar = project.accessrequests.create({})
 g_ar = group.accessrequests.create({})
 # end create
@@ -28,9 +19,6 @@ ar.approve(access_level=gitlab.MASTER_ACCESS)  # explicitly set access level
 # end approve
 
 # delete
-gl.project_accessrequests.delete(user_id, project_id=1)
-gl.group_accessrequests.delete(user_id, group_id=1)
-# or
 project.accessrequests.delete(user_id)
 group.accessrequests.delete(user_id)
 # or
diff --git a/docs/gl_objects/access_requests.rst b/docs/gl_objects/access_requests.rst
index a9e6d9b..f64e795 100644
--- a/docs/gl_objects/access_requests.rst
+++ b/docs/gl_objects/access_requests.rst
@@ -2,14 +2,41 @@
 Access requests
 ###############
 
-Use :class:`~gitlab.objects.ProjectAccessRequest` and
-:class:`~gitlab.objects.GroupAccessRequest` objects to manipulate access
-requests for projects and groups. The
-:attr:`gitlab.Gitlab.project_accessrequests`,
-:attr:`gitlab.Gitlab.group_accessrequests`, :attr:`Project.accessrequests
-<gitlab.objects.Project.accessrequests>` and :attr:`Group.accessrequests
-<gitlab.objects.Group.accessrequests>` manager objects provide helper
-functions.
+Users can request access to groups and projects.
+
+When access is granted the user should be given a numerical access level. The
+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.OWNER_ACCESS``: ``50``
+
+References
+----------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectAccessRequest`
+  + :class:`gitlab.v4.objects.ProjectAccessRequestManager`
+  + :attr:`gitlab.v4.objects.Project.accessrequests`
+  + :class:`gitlab.v4.objects.GroupAccessRequest`
+  + :class:`gitlab.v4.objects.GroupAccessRequestManager`
+  + :attr:`gitlab.v4.objects.Group.accessrequests`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectAccessRequest`
+  + :class:`gitlab.v3.objects.ProjectAccessRequestManager`
+  + :attr:`gitlab.v3.objects.Project.accessrequests`
+  + :attr:`gitlab.Gitlab.project_accessrequests`
+  + :class:`gitlab.v3.objects.GroupAccessRequest`
+  + :class:`gitlab.v3.objects.GroupAccessRequestManager`
+  + :attr:`gitlab.v3.objects.Group.accessrequests`
+  + :attr:`gitlab.Gitlab.group_accessrequests`
+
+* GitLab API: https://docs.gitlab.com/ce/api/access_requests.html
 
 Examples
 --------
diff --git a/docs/gl_objects/branches.py b/docs/gl_objects/branches.py
index b485ee0..b80dfc0 100644
--- a/docs/gl_objects/branches.py
+++ b/docs/gl_objects/branches.py
@@ -1,27 +1,22 @@
 # list
-branches = gl.project_branches.list(project_id=1)
-# or
 branches = project.branches.list()
 # end list
 
 # get
-branch = gl.project_branches.get(project_id=1, id='master')
-# or
 branch = project.branches.get('master')
 # end get
 
 # create
-branch = gl.project_branches.create({'branch_name': 'feature1',
-                                     'ref': 'master'},
-                                    project_id=1)
-# or
+# v4
+branch = project.branches.create({'branch': 'feature1',
+                                  'ref': 'master'})
+
+#v3
 branch = project.branches.create({'branch_name': 'feature1',
                                   'ref': 'master'})
 # end create
 
 # delete
-gl.project_branches.delete(project_id=1, id='feature1')
-# or
 project.branches.delete('feature1')
 # or
 branch.delete()
diff --git a/docs/gl_objects/branches.rst b/docs/gl_objects/branches.rst
index 50b97a7..279ca0c 100644
--- a/docs/gl_objects/branches.rst
+++ b/docs/gl_objects/branches.rst
@@ -2,15 +2,25 @@
 Branches
 ########
 
-Use :class:`~gitlab.objects.ProjectBranch` objects to manipulate repository
-branches.
+References
+----------
 
-To create :class:`~gitlab.objects.ProjectBranch` objects use the
-:attr:`gitlab.Gitlab.project_branches` or :attr:`Project.branches
-<gitlab.objects.Project.branches>` managers.
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectBranch`
+  + :class:`gitlab.v4.objects.ProjectBranchManager`
+  + :attr:`gitlab.v4.objects.Project.branches`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectBranch`
+  + :class:`gitlab.v3.objects.ProjectBranchManager`
+  + :attr:`gitlab.v3.objects.Project.branches`
+
+* GitLab API: https://docs.gitlab.com/ce/api/branches.html
 
 Examples
-========
+--------
 
 Get the list of branches for a repository:
 
@@ -41,10 +51,13 @@ Protect/unprotect a repository branch:
 .. literalinclude:: branches.py
    :start-after: # protect
    :end-before: # end protect
-   
+
 .. note::
-   
-   By default, developers will not be able to push or merge into
-   protected branches. This can be changed by passing ``developers_can_push``
-   or ``developers_can_merge`` like so: 
-   ``branch.protect(developers_can_push=False, developers_can_merge=True)``
+
+   By default, developers are not authorized to push or merge into protected
+   branches. This can be changed by passing ``developers_can_push`` or
+   ``developers_can_merge``:
+
+   .. code-block:: python
+
+      branch.protect(developers_can_push=True, developers_can_merge=True)
diff --git a/docs/gl_objects/builds.py b/docs/gl_objects/builds.py
index 855b7c8..e125b39 100644
--- a/docs/gl_objects/builds.py
+++ b/docs/gl_objects/builds.py
@@ -1,19 +1,12 @@
 # var list
-variables = gl.project_variables.list(project_id=1)
-# or
 variables = project.variables.list()
 # end var list
 
 # var get
-var = gl.project_variables.get(var_key, project_id=1)
-# or
 var = project.variables.get(var_key)
 # end var get
 
 # var create
-var = gl.project_variables.create({'key': 'key1', 'value': 'value1'},
-                                  project_id=1)
-# or
 var = project.variables.create({'key': 'key1', 'value': 'value1'})
 # end var create
 
@@ -23,58 +16,47 @@ var.save()
 # end var update
 
 # var delete
-gl.project_variables.delete(var_key)
-# or
-project.variables.delete()
+project.variables.delete(var_key)
 # or
 var.delete()
 # end var delete
 
 # trigger list
-triggers = gl.project_triggers.list(project_id=1)
-# or
 triggers = project.triggers.list()
 # end trigger list
 
 # trigger get
-trigger = gl.project_triggers.get(trigger_token, project_id=1)
-# or
 trigger = project.triggers.get(trigger_token)
 # end trigger get
 
 # trigger create
-trigger = gl.project_triggers.create({}, project_id=1)
-# or
 trigger = project.triggers.create({})
 # end trigger create
 
 # trigger delete
-gl.project_triggers.delete(trigger_token)
-# or
-project.triggers.delete()
+project.triggers.delete(trigger_token)
 # or
 trigger.delete()
 # end trigger delete
 
 # list
-builds = gl.project_builds.list(project_id=1)
-# or
-builds = project.builds.list()
+builds = project.builds.list()  # v3
+jobs = project.jobs.list()  # v4
 # end list
 
 # commit list
+# v3 only
 commit = gl.project_commits.get(commit_sha, project_id=1)
 builds = commit.builds()
 # end commit list
 
 # get
-build = gl.project_builds.get(build_id, project_id=1)
-# or
-project.builds.get(build_id)
+project.builds.get(build_id)  # v3
+project.jobs.get(job_id)  # v4
 # end get
 
 # artifacts
-build.artifacts()
+build_or_job.artifacts()
 # end artifacts
 
 # stream artifacts
@@ -86,33 +68,32 @@ class Foo(object):
         self._fd.write(chunk)
 
 target = Foo()
-build.artifacts(streamed=True, action=target)
+build_or_job.artifacts(streamed=True, action=target)
 del(target)  # flushes data on disk
 # end stream artifacts
 
 # keep artifacts
-build.keep_artifacts()
+build_or_job.keep_artifacts()
 # end keep artifacts
 
 # trace
-build.trace()
+build_or_job.trace()
 # end trace
 
 # retry
-build.cancel()
-build.retry()
+build_or_job.cancel()
+build_or_job.retry()
 # end retry
 
 # erase
-build.erase()
+build_or_job.erase()
 # end erase
 
 # play
-build.play()
+build_or_job.play()
 # end play
 
 # trigger run
-p = gl.projects.get(project_id)
-p.trigger_build('master', trigger_token,
-                {'extra_var1': 'foo', 'extra_var2': 'bar'})
+project.trigger_build('master', trigger_token,
+                      {'extra_var1': 'foo', 'extra_var2': 'bar'})
 # end trigger run
diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst
index b20ca77..52bdb1a 100644
--- a/docs/gl_objects/builds.rst
+++ b/docs/gl_objects/builds.rst
@@ -1,16 +1,33 @@
-######
-Builds
-######
+###############################
+Jobs (v4 API) / Builds (v3 API)
+###############################
 
-Build triggers
-==============
+Build and job are two classes representing the same object. Builds are used in
+v3 API, jobs in v4 API.
 
-Build triggers provide a way to interact with the GitLab CI. Using a trigger a
-user or an application can run a new build for a specific commit.
+Triggers
+========
 
-* Object class: :class:`~gitlab.objects.ProjectTrigger`
-* Manager objects: :attr:`gitlab.Gitlab.project_triggers`,
-  :attr:`Project.triggers <gitlab.objects.Project.triggers>`
+Triggers provide a way to interact with the GitLab CI. Using a trigger a user
+or an application can run a new build/job for a specific commit.
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectTrigger`
+  + :class:`gitlab.v4.objects.ProjectTriggerManager`
+  + :attr:`gitlab.v4.objects.Project.triggers`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectTrigger`
+  + :class:`gitlab.v3.objects.ProjectTriggerManager`
+  + :attr:`gitlab.v3.objects.Project.triggers`
+  + :attr:`gitlab.Gitlab.project_triggers`
+
+* GitLab API: https://docs.gitlab.com/ce/api/pipeline_triggers.html
 
 Examples
 --------
@@ -39,14 +56,29 @@ Remove a trigger:
    :start-after: # trigger delete
    :end-before: # end trigger delete
 
-Build variables
-===============
+Project variables
+=================
+
+You can associate variables to projects to modify the build/job script
+behavior.
+
+Reference
+---------
 
-You can associate variables to builds to modify the build script behavior.
+* v4 API
 
-* Object class: :class:`~gitlab.objects.ProjectVariable`
-* Manager objects: :attr:`gitlab.Gitlab.project_variables`,
-  :attr:`gitlab.objects.Project.variables`
+  + :class:`gitlab.v4.objects.ProjectVariable`
+  + :class:`gitlab.v4.objects.ProjectVariableManager`
+  + :attr:`gitlab.v4.objects.Project.variables`
+
+* v3 API
+
+  + :class:`gitlab.v3.objects.ProjectVariable`
+  + :class:`gitlab.v3.objects.ProjectVariableManager`
+  + :attr:`gitlab.v3.objects.Project.variables`
+  + :attr:`gitlab.Gitlab.project_variables`
+
+* GitLab API: https://docs.gitlab.com/ce/api/project_level_variables.html
 
 Examples
 --------
@@ -81,49 +113,63 @@ Remove a variable:
    :start-after: # var delete
    :end-before: # end var delete
 
-Builds
-======
+Builds/Jobs
+===========
+
+Builds/Jobs are associated to projects and commits. They provide information on
+the builds/jobs that have been run, and methods to manipulate them.
+
+Reference
+---------
+
+* v4 API
+
+  + :class:`gitlab.v4.objects.ProjectJob`
+  + :class:`gitlab.v4.objects.ProjectJobManager`
+  + :attr:`gitlab.v4.objects.Project.jobs`
+
+* v3 API
 
-Builds are associated to projects and commits. They provide information on the
-build that have been run, and methods to manipulate those builds.
+  + :class:`gitlab.v3.objects.ProjectJob`
+  + :class:`gitlab.v3.objects.ProjectJobManager`
+  + :attr:`gitlab.v3.objects.Project.jobs`
+  + :attr:`gitlab.Gitlab.project_jobs`
 
-* Object class: :class:`~gitlab.objects.ProjectBuild`
-* Manager objects: :attr:`gitlab.Gitlab.project_builds`,
-  :attr:`gitlab.objects.Project.builds`
+* GitLab API: https://docs.gitlab.com/ce/api/jobs.html
 
 Examples
 --------
 
-Build are usually automatically triggered, but you can explicitly trigger a
-new build:
+Jobs are usually automatically triggered, but you can explicitly trigger a new
+job:
 
-Trigger a new build on a project:
+Trigger a new job on a project:
 
 .. literalinclude:: builds.py
    :start-after: # trigger run
    :end-before: # end trigger run
 
-List builds for the project:
+List jobs for the project:
 
 .. literalinclude:: builds.py
    :start-after: # list
    :end-before: # end list
 
 To list builds for a specific commit, create a
-:class:`~gitlab.objects.ProjectCommit` object and use its
-:attr:`~gitlab.objects.ProjectCommit.builds` method:
+:class:`~gitlab.v3.objects.ProjectCommit` object and use its
+:attr:`~gitlab.v3.objects.ProjectCommit.builds` method (v3 only):
 
 .. literalinclude:: builds.py
    :start-after: # commit list
    :end-before: # end commit list
 
-Get a build:
+Get a job:
 
 .. literalinclude:: builds.py
    :start-after: # get
    :end-before: # end get
 
-Get a build artifacts:
+Get a job artifact:
 
 .. literalinclude:: builds.py
    :start-after: # artifacts
@@ -142,13 +188,13 @@ stream:
    :start-after: # stream artifacts
    :end-before: # end stream artifacts
 
-Mark a build artifact as kept when expiration is set:
+Mark a job artifact as kept when expiration is set:
 
 .. literalinclude:: builds.py
    :start-after: # keep artifacts
    :end-before: # end keep artifacts
 
-Get a build trace:
+Get a job trace:
 
 .. literalinclude:: builds.py
    :start-after: # trace
@@ -159,19 +205,19 @@ Get a build trace:
    Traces are entirely stored in memory unless you use the streaming feature.
    See :ref:`the artifacts example <streaming_example>`.
 
-Cancel/retry a build:
+Cancel/retry a job:
 
 .. literalinclude:: builds.py
    :start-after: # retry
    :end-before: # end retry
 
-Play (trigger) a build:
+Play (trigger) a job:
 
 .. literalinclude:: builds.py
    :start-after: # play
    :end-before: # end play
 
-Erase a build (artifacts and trace):
+Erase a job (artifacts and trace):
 
 .. literalinclude:: builds.py
    :start-after: # erase
diff --git a/docs/gl_objects/commits.py b/docs/gl_objects/commits.py
index befebd5..f7e73e5 100644
--- a/docs/gl_objects/commits.py
+++ b/docs/gl_objects/commits.py
@@ -1,6 +1,4 @@
 # list
-commits = gl.project_commits.list(project_id=1)
-# or
 commits = project.commits.list()
 # end list
 
@@ -13,7 +11,8 @@ commits = project.commits.list(since='2016-01-01T00:00:00Z')
 # See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
 # for actions detail
 data = {
-    'branch_name': 'master',
+    'branch_name': 'master',  # v3
+    'branch': 'master',  # v4
     'commit_message': 'blah blah blah',
     'actions': [
         {
@@ -24,14 +23,10 @@ data = {
     ]
 }
 
-commit = gl.project_commits.create(data, project_id=1)
-# or
 commit = project.commits.create(data)
 # end create
 
 # get
-commit = gl.project_commits.get('e3d5a71b', project_id=1)
-# or
 commit = project.commits.get('e3d5a71b')
 # end get
 
@@ -44,10 +39,6 @@ commit.cherry_pick(branch='target_branch')
 # end cherry
 
 # comments list
-comments = gl.project_commit_comments.list(project_id=1, commit_id='master')
-# or
-comments = project.commit_comments.list(commit_id='a5fe4c8')
-# or
 comments = commit.comments.list()
 # end comments list
 
@@ -62,10 +53,6 @@ commit = commit.comments.create({'note': 'This is another comment',
 # end comments create
 
 # statuses list
-statuses = gl.project_commit_statuses.list(project_id=1, commit_id='master')
-# or
-statuses = project.commit_statuses.list(commit_id='a5fe4c8')
-# or
 statuses = commit.statuses.list()
 # end statuses list
 
diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst
index 6fef8bf..9267cae 100644
--- a/docs/gl_objects/commits.rst
+++ b/docs/gl_objects/commits.rst
@@ -5,9 +5,24 @@ Commits
 Commits
 =======
 
-* Object class: :class:`~gitlab.objects.ProjectCommit`
-* Manager objects: :attr:`gitlab.Gitlab.project_commits`,
-  :attr:`gitlab.objects.Project.commits`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectCommit`
+  + :class:`gitlab.v4.objects.ProjectCommitManager`
+  + :attr:`gitlab.v4.objects.Project.commits`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectCommit`
+  + :class:`gitlab.v3.objects.ProjectCommitManager`
+  + :attr:`gitlab.v3.objects.Project.commits`
+  + :attr:`gitlab.Gitlab.project_commits`
+
+* GitLab API: https://docs.gitlab.com/ce/api/commits.html
+
 
 Examples
 --------
@@ -52,10 +67,24 @@ Cherry-pick a commit into another branch:
 Commit comments
 ===============
 
-* Object class: :class:`~gitlab.objects.ProjectCommiComment`
-* Manager objects: :attr:`gitlab.Gitlab.project_commit_comments`,
-  :attr:`gitlab.objects.Project.commit_comments`,
-  :attr:`gitlab.objects.ProjectCommit.comments`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectCommitComment`
+  + :class:`gitlab.v4.objects.ProjectCommitCommentManager`
+  + :attr:`gitlab.v4.objects.Commit.comments`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectCommit`
+  + :class:`gitlab.v3.objects.ProjectCommitManager`
+  + :attr:`gitlab.v3.objects.Commit.comments`
+  + :attr:`gitlab.v3.objects.Project.commit_comments`
+  + :attr:`gitlab.Gitlab.project_commit_comments`
+
+* GitLab API: https://docs.gitlab.com/ce/api/commits.html
 
 Examples
 --------
@@ -75,10 +104,24 @@ Add a comment on a commit:
 Commit status
 =============
 
-* Object class: :class:`~gitlab.objects.ProjectCommitStatus`
-* Manager objects: :attr:`gitlab.Gitlab.project_commit_statuses`,
-  :attr:`gitlab.objects.Project.commit_statuses`,
-  :attr:`gitlab.objects.ProjectCommit.statuses`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectCommitStatus`
+  + :class:`gitlab.v4.objects.ProjectCommitStatusManager`
+  + :attr:`gitlab.v4.objects.Commit.statuses`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectCommit`
+  + :class:`gitlab.v3.objects.ProjectCommitManager`
+  + :attr:`gitlab.v3.objects.Commit.statuses`
+  + :attr:`gitlab.v3.objects.Project.commit_statuses`
+  + :attr:`gitlab.Gitlab.project_commit_statuses`
+
+* GitLab API: https://docs.gitlab.com/ce/api/commits.html
 
 Examples
 --------
diff --git a/docs/gl_objects/deploy_keys.py b/docs/gl_objects/deploy_keys.py
index 84da079..ccdf30e 100644
--- a/docs/gl_objects/deploy_keys.py
+++ b/docs/gl_objects/deploy_keys.py
@@ -7,29 +7,19 @@ key = gl.deploykeys.get(key_id)
 # end global get
 
 # list
-keys = gl.project_keys.list(project_id=1)
-# or
 keys = project.keys.list()
 # end list
 
 # get
-key = gl.project_keys.get(key_id, project_id=1)
-# or
 key = project.keys.get(key_id)
 # end get
 
 # create
-key = gl.project_keys.create({'title': 'jenkins key',
-                              'key': open('/home/me/.ssh/id_rsa.pub').read()},
-                             project_id=1)
-# or
 key = project.keys.create({'title': 'jenkins key',
                            'key': open('/home/me/.ssh/id_rsa.pub').read()})
 # end create
 
 # delete
-key = gl.project_keys.delete(key_id, project_id=1)
-# or
 key = project.keys.list(key_id)
 # or
 key.delete()
@@ -40,5 +30,6 @@ project.keys.enable(key_id)
 # end enable
 
 # disable
-project.keys.disable(key_id)
+project_key.delete()  # v4
+project.keys.disable(key_id)  # v3
 # end disable
diff --git a/docs/gl_objects/deploy_keys.rst b/docs/gl_objects/deploy_keys.rst
index 28033cb..059b01f 100644
--- a/docs/gl_objects/deploy_keys.rst
+++ b/docs/gl_objects/deploy_keys.rst
@@ -5,10 +5,22 @@ Deploy keys
 Deploy keys
 ===========
 
-Deploy keys allow read-only access to multiple projects with a single SSH key.
+Reference
+---------
 
-* Object class: :class:`~gitlab.objects.DeployKey`
-* Manager object: :attr:`gitlab.Gitlab.deploykeys`
+* v4 API:
+
+  + :class:`gitlab.v4.objects.DeployKey`
+  + :class:`gitlab.v4.objects.DeployKeyManager`
+  + :attr:`gitlab.Gitlab.deploykeys`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Key`
+  + :class:`gitlab.v3.objects.KeyManager`
+  + :attr:`gitlab.Gitlab.deploykeys`
+
+* GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html
 
 Examples
 --------
@@ -30,9 +42,23 @@ Deploy keys for projects
 
 Deploy keys can be managed on a per-project basis.
 
-* Object class: :class:`~gitlab.objects.ProjectKey`
-* Manager objects: :attr:`gitlab.Gitlab.project_keys` and :attr:`Project.keys
-  <gitlab.objects.Project.keys>`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectKey`
+  + :class:`gitlab.v4.objects.ProjectKeyManager`
+  + :attr:`gitlab.v4.objects.Project.keys`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectKey`
+  + :class:`gitlab.v3.objects.ProjectKeyManager`
+  + :attr:`gitlab.v3.objects.Project.keys`
+  + :attr:`gitlab.Gitlab.project_keys`
+
+* GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html
 
 Examples
 --------
diff --git a/docs/gl_objects/deployments.py b/docs/gl_objects/deployments.py
index fe1613a..5084b4d 100644
--- a/docs/gl_objects/deployments.py
+++ b/docs/gl_objects/deployments.py
@@ -1,11 +1,7 @@
 # list
-deployments = gl.project_deployments.list(project_id=1)
-# or
 deployments = project.deployments.list()
 # end list
 
 # get
-deployment = gl.project_deployments.get(deployment_id, project_id=1)
-# or
 deployment = project.deployments.get(deployment_id)
 # end get
diff --git a/docs/gl_objects/deployments.rst b/docs/gl_objects/deployments.rst
index 1a679da..37e9468 100644
--- a/docs/gl_objects/deployments.rst
+++ b/docs/gl_objects/deployments.rst
@@ -2,10 +2,23 @@
 Deployments
 ###########
 
-Use :class:`~gitlab.objects.ProjectDeployment` objects to manipulate project
-deployments. The :attr:`gitlab.Gitlab.project_deployments`, and
-:attr:`Project.deployments <gitlab.objects.Project.deployments>` manager
-objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectDeployment`
+  + :class:`gitlab.v4.objects.ProjectDeploymentManager`
+  + :attr:`gitlab.v4.objects.Project.deployments`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectDeployment`
+  + :class:`gitlab.v3.objects.ProjectDeploymentManager`
+  + :attr:`gitlab.v3.objects.Project.deployments`
+  + :attr:`gitlab.Gitlab.project_deployments`
+
+* GitLab API: https://docs.gitlab.com/ce/api/deployments.html
 
 Examples
 --------
diff --git a/docs/gl_objects/environments.py b/docs/gl_objects/environments.py
index 80d77c9..3ca6fc1 100644
--- a/docs/gl_objects/environments.py
+++ b/docs/gl_objects/environments.py
@@ -1,19 +1,12 @@
 # list
-environments = gl.project_environments.list(project_id=1)
-# or
 environments = project.environments.list()
 # end list
 
 # get
-environment = gl.project_environments.get(environment_id, project_id=1)
-# or
 environment = project.environments.get(environment_id)
 # end get
 
 # create
-environment = gl.project_environments.create({'name': 'production'},
-                                             project_id=1)
-# or
 environment = project.environments.create({'name': 'production'})
 # end create
 
@@ -23,9 +16,7 @@ environment.save()
 # end update
 
 # delete
-environment = gl.project_environments.delete(environment_id, project_id=1)
-# or
-environment = project.environments.list(environment_id)
+environment = project.environments.delete(environment_id)
 # or
 environment.delete()
 # end delete
diff --git a/docs/gl_objects/environments.rst b/docs/gl_objects/environments.rst
index 83d080b..d94c453 100644
--- a/docs/gl_objects/environments.rst
+++ b/docs/gl_objects/environments.rst
@@ -2,10 +2,23 @@
 Environments
 ############
 
-Use :class:`~gitlab.objects.ProjectEnvironment` objects to manipulate
-environments for projects. The :attr:`gitlab.Gitlab.project_environments` and
-:attr:`Project.environments <gitlab.objects.Project.environments>` manager
-objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectEnvironment`
+  + :class:`gitlab.v4.objects.ProjectEnvironmentManager`
+  + :attr:`gitlab.v4.objects.Project.environments`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectEnvironment`
+  + :class:`gitlab.v3.objects.ProjectEnvironmentManager`
+  + :attr:`gitlab.v3.objects.Project.environments`
+  + :attr:`gitlab.Gitlab.project_environments`
+
+* GitLab API: https://docs.gitlab.com/ce/api/environments.html
 
 Examples
 --------
diff --git a/docs/gl_objects/groups.py b/docs/gl_objects/groups.py
index 8b4e888..f1a2a8f 100644
--- a/docs/gl_objects/groups.py
+++ b/docs/gl_objects/groups.py
@@ -2,18 +2,12 @@
 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
@@ -32,22 +26,14 @@ 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': gitlab.GUEST_ACCESS},
-                                 group_id=1)
-# or
 member = group.members.create({'user_id': user_id,
                                'access_level': gitlab.GUEST_ACCESS})
 # end member create
@@ -58,8 +44,6 @@ 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()
diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst
index b2c0ed8..5e413af 100644
--- a/docs/gl_objects/groups.rst
+++ b/docs/gl_objects/groups.rst
@@ -5,8 +5,22 @@ Groups
 Groups
 ======
 
-Use :class:`~gitlab.objects.Group` objects to manipulate groups. The
-:attr:`gitlab.Gitlab.groups` manager object provides helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Group`
+  + :class:`gitlab.v4.objects.GroupManager`
+  + :attr:`gitlab.Gitlab.groups`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Group`
+  + :class:`gitlab.v3.objects.GroupManager`
+  + :attr:`gitlab.Gitlab.groups`
+
+* GitLab API: https://docs.gitlab.com/ce/api/groups.html
 
 Examples
 --------
@@ -17,12 +31,6 @@ List the groups:
    :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
@@ -67,18 +75,35 @@ Remove a group:
 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 constants define the supported access levels:
+
+* ``gitlab.GUEST_ACCESS = 10``
+* ``gitlab.REPORTER_ACCESS = 20``
+* ``gitlab.DEVELOPER_ACCESS = 30``
+* ``gitlab.MASTER_ACCESS = 40``
+* ``gitlab.OWNER_ACCESS = 50``
 
-The following :class:`~gitlab.objects.Group` attributes define the supported
-access levels:
+Reference
+---------
 
-* ``GUEST_ACCESS = 10``
-* ``REPORTER_ACCESS = 20``
-* ``DEVELOPER_ACCESS = 30``
-* ``MASTER_ACCESS = 40``
-* ``OWNER_ACCESS = 50``
+* v4 API:
+
+  + :class:`gitlab.v4.objects.GroupMember`
+  + :class:`gitlab.v4.objects.GroupMemberManager`
+  + :attr:`gitlab.v4.objects.Group.members`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.GroupMember`
+  + :class:`gitlab.v3.objects.GroupMemberManager`
+  + :attr:`gitlab.v3.objects.Group.members`
+  + :attr:`gitlab.Gitlab.group_members`
+
+* GitLab API: https://docs.gitlab.com/ce/api/groups.html
+
+
+Examples
+--------
 
 List group members:
 
diff --git a/docs/gl_objects/issues.py b/docs/gl_objects/issues.py
index df13c20..de4a356 100644
--- a/docs/gl_objects/issues.py
+++ b/docs/gl_objects/issues.py
@@ -9,8 +9,6 @@ tagged_issues = gl.issues.list(labels=['foo', 'bar'])
 # end filtered list
 
 # group issues list
-issues = gl.group_issues.list(group_id=1)
-# or
 issues = group.issues.list()
 # Filter using the state, labels and milestone parameters
 issues = group.issues.list(milestone='1.0', state='opened')
@@ -19,8 +17,6 @@ issues = group.issues.list(order_by='created_at', sort='desc')
 # end group issues list
 
 # project issues list
-issues = gl.project_issues.list(project_id=1)
-# or
 issues = project.issues.list()
 # Filter using the state, labels and milestone parameters
 issues = project.issues.list(milestone='1.0', state='opened')
@@ -29,16 +25,10 @@ issues = project.issues.list(order_by='created_at', sort='desc')
 # end project issues list
 
 # project issues get
-issue = gl.project_issues.get(issue_id, project_id=1)
-# or
 issue = project.issues.get(issue_id)
 # end project issues get
 
 # project issues create
-issue = gl.project_issues.create({'title': 'I have a bug',
-                                  'description': 'Something useful here.'},
-                                 project_id=1)
-# or
 issue = project.issues.create({'title': 'I have a bug',
                                'description': 'Something useful here.'})
 # end project issues create
@@ -58,8 +48,6 @@ issue.save()
 # end project issue open_close
 
 # project issue delete
-gl.project_issues.delete(issue_id, project_id=1)
-# or
 project.issues.delete(issue_id)
 # pr
 issue.delete()
diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst
index 259c79f..b3b1cf1 100644
--- a/docs/gl_objects/issues.rst
+++ b/docs/gl_objects/issues.rst
@@ -5,9 +5,22 @@ Issues
 Reported issues
 ===============
 
-Use :class:`~gitlab.objects.Issues` objects to manipulate issues the
-authenticated user reported. The :attr:`gitlab.Gitlab.issues` manager object
-provides helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Issue`
+  + :class:`gitlab.v4.objects.IssueManager`
+  + :attr:`gitlab.Gitlab.issues`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Issue`
+  + :class:`gitlab.v3.objects.IssueManager`
+  + :attr:`gitlab.Gitlab.issues`
+
+* GitLab API: https://docs.gitlab.com/ce/api/issues.html
 
 Examples
 --------
@@ -28,9 +41,23 @@ Use the ``state`` and ``label`` parameters to filter the results. Use the
 Group issues
 ============
 
-Use :class:`~gitlab.objects.GroupIssue` objects to manipulate issues. The
-:attr:`gitlab.Gitlab.project_issues` and :attr:`Group.issues
-<gitlab.objects.Group.issues>` manager objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.GroupIssue`
+  + :class:`gitlab.v4.objects.GroupIssueManager`
+  + :attr:`gitlab.v4.objects.Group.issues`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.GroupIssue`
+  + :class:`gitlab.v3.objects.GroupIssueManager`
+  + :attr:`gitlab.v3.objects.Group.issues`
+  + :attr:`gitlab.Gitlab.group_issues`
+
+* GitLab API: https://docs.gitlab.com/ce/api/issues.html
 
 Examples
 --------
@@ -44,9 +71,23 @@ List the group issues:
 Project issues
 ==============
 
-Use :class:`~gitlab.objects.ProjectIssue` objects to manipulate issues. The
-:attr:`gitlab.Gitlab.project_issues` and :attr:`Project.issues
-<gitlab.objects.Project.issues>` manager objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectIssue`
+  + :class:`gitlab.v4.objects.ProjectIssueManager`
+  + :attr:`gitlab.v4.objects.Project.issues`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectIssue`
+  + :class:`gitlab.v3.objects.ProjectIssueManager`
+  + :attr:`gitlab.v3.objects.Project.issues`
+  + :attr:`gitlab.Gitlab.project_issues`
+
+* GitLab API: https://docs.gitlab.com/ce/api/issues.html
 
 Examples
 --------
diff --git a/docs/gl_objects/labels.py b/docs/gl_objects/labels.py
index 9a36363..57892b5 100644
--- a/docs/gl_objects/labels.py
+++ b/docs/gl_objects/labels.py
@@ -1,19 +1,12 @@
 # list
-labels = gl.project_labels.list(project_id=1)
-# or
 labels = project.labels.list()
 # end list
 
 # get
-label = gl.project_labels.get(label_name, project_id=1)
-# or
 label = project.labels.get(label_name)
 # end get
 
 # create
-label = gl.project_labels.create({'name': 'foo', 'color': '#8899aa'},
-                                 project_id=1)
-# or
 label = project.labels.create({'name': 'foo', 'color': '#8899aa'})
 # end create
 
@@ -27,8 +20,6 @@ label.save()
 # end update
 
 # delete
-gl.project_labels.delete(label_id, project_id=1)
-# or
 project.labels.delete(label_id)
 # or
 label.delete()
diff --git a/docs/gl_objects/labels.rst b/docs/gl_objects/labels.rst
index 3973b0b..d444217 100644
--- a/docs/gl_objects/labels.rst
+++ b/docs/gl_objects/labels.rst
@@ -2,9 +2,23 @@
 Labels
 ######
 
-Use :class:`~gitlab.objects.ProjectLabel` objects to manipulate labels for
-projects. The :attr:`gitlab.Gitlab.project_labels` and :attr:`Project.labels
-<gitlab.objects.Project.labels>` manager objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectLabel`
+  + :class:`gitlab.v4.objects.ProjectLabelManager`
+  + :attr:`gitlab.v4.objects.Project.labels`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectLabel`
+  + :class:`gitlab.v3.objects.ProjectLabelManager`
+  + :attr:`gitlab.v3.objects.Project.labels`
+  + :attr:`gitlab.Gitlab.project_labels`
+
+* GitLab API: https://docs.gitlab.com/ce/api/labels.html
 
 Examples
 --------
diff --git a/docs/gl_objects/messages.rst b/docs/gl_objects/messages.rst
index 9f183ba..452370d 100644
--- a/docs/gl_objects/messages.rst
+++ b/docs/gl_objects/messages.rst
@@ -6,8 +6,22 @@ You can use broadcast messages to display information on all pages of the
 gitlab web UI. You must have administration permissions to manipulate broadcast
 messages.
 
-* Object class: :class:`gitlab.objects.BroadcastMessage`
-* Manager object: :attr:`gitlab.Gitlab.broadcastmessages`
+References
+----------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.BroadcastMessage`
+  + :class:`gitlab.v4.objects.BroadcastMessageManager`
+  + :attr:`gitlab.Gitlab.broadcastmessages`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.BroadcastMessage`
+  + :class:`gitlab.v3.objects.BroadcastMessageManager`
+  + :attr:`gitlab.Gitlab.broadcastmessages`
+
+* GitLab API: https://docs.gitlab.com/ce/api/broadcast_messages.html
 
 Examples
 --------
diff --git a/docs/gl_objects/milestones.py b/docs/gl_objects/milestones.py
index 83065fc..19770bc 100644
--- a/docs/gl_objects/milestones.py
+++ b/docs/gl_objects/milestones.py
@@ -1,24 +1,16 @@
 # list
-milestones = gl.project_milestones.list(project_id=1)
-# or
 milestones = project.milestones.list()
 # end list
 
 # filter
-milestones = gl.project_milestones.list(project_id=1, state='closed')
-# or
 milestones = project.milestones.list(state='closed')
 # end filter
 
 # get
-milestone = gl.project_milestones.get(milestone_id, project_id=1)
-# or
 milestone = project.milestones.get(milestone_id)
 # end get
 
 # create
-milestone = gl.project_milestones.create({'title': '1.0'}, project_id=1)
-# or
 milestone = project.milestones.create({'title': '1.0'})
 # end create
 
diff --git a/docs/gl_objects/milestones.rst b/docs/gl_objects/milestones.rst
index 47e585a..fbe5d87 100644
--- a/docs/gl_objects/milestones.rst
+++ b/docs/gl_objects/milestones.rst
@@ -2,9 +2,23 @@
 Milestones
 ##########
 
-Use :class:`~gitlab.objects.ProjectMilestone` objects to manipulate milestones.
-The :attr:`gitlab.Gitlab.project_milestones` and :attr:`Project.milestones
-<gitlab.objects.Project.milestones>` manager objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectMilestone`
+  + :class:`gitlab.v4.objects.ProjectMilestoneManager`
+  + :attr:`gitlab.v4.objects.Project.milestones`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectMilestone`
+  + :class:`gitlab.v3.objects.ProjectMilestoneManager`
+  + :attr:`gitlab.v3.objects.Project.milestones`
+  + :attr:`gitlab.Gitlab.project_milestones`
+
+* GitLab API: https://docs.gitlab.com/ce/api/milestones.html
 
 Examples
 --------
@@ -58,4 +72,4 @@ List the merge requests related to a milestone:
 
 .. literalinclude:: milestones.py
    :start-after: # merge_requests
-   :end-before: # end merge_requests
\ No newline at end of file
+   :end-before: # end merge_requests
diff --git a/docs/gl_objects/mrs.py b/docs/gl_objects/mrs.py
index 021338d..bc30b43 100644
--- a/docs/gl_objects/mrs.py
+++ b/docs/gl_objects/mrs.py
@@ -1,6 +1,4 @@
 # list
-mrs = gl.project_mergerequests.list(project_id=1)
-# or
 mrs = project.mergerequests.list()
 # end list
 
@@ -9,17 +7,10 @@ mrs = project.mergerequests.list(state='merged', order_by='updated_at')
 # end filtered list
 
 # get
-mr = gl.project_mergerequests.get(mr_id, project_id=1)
-# or
 mr = project.mergerequests.get(mr_id)
 # end get
 
 # create
-mr = gl.project_mergerequests.create({'source_branch': 'cool_feature',
-                                      'target_branch': 'master',
-                                      'title': 'merge cool feature'},
-                                     project_id=1)
-# or
 mr = project.mergerequests.create({'source_branch': 'cool_feature',
                                    'target_branch': 'master',
                                    'title': 'merge cool feature'})
@@ -36,8 +27,6 @@ mr.save()
 # end state
 
 # delete
-gl.project_mergerequests.delete(mr_id, project_id=1)
-# or
 project.mergerequests.delete(mr_id)
 # or
 mr.delete()
@@ -48,7 +37,8 @@ mr.merge()
 # end merge
 
 # cancel
-mr.cancel_merge_when_build_succeeds()
+mr.cancel_merge_when_build_succeeds()  # v3
+mr.cancel_merge_when_pipeline_succeeds()  # v4
 # end cancel
 
 # issues
diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst
index d6e10d3..04d413c 100644
--- a/docs/gl_objects/mrs.rst
+++ b/docs/gl_objects/mrs.rst
@@ -5,9 +5,26 @@ 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.
 
-* Object class: :class:`~gitlab.objects.ProjectMergeRequest`
-* Manager objects: :attr:`gitlab.Gitlab.project_mergerequests`,
-  :attr:`Project.mergerequests <gitlab.objects.Project.mergerequests>`
+The v3 API uses the ``id`` attribute to identify a merge request, the v4 API
+uses the ``iid`` attribute.
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectMergeRequest`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestManager`
+  + :attr:`gitlab.v4.objects.Project.mergerequests`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectMergeRequest`
+  + :class:`gitlab.v3.objects.ProjectMergeRequestManager`
+  + :attr:`gitlab.v3.objects.Project.mergerequests`
+  + :attr:`gitlab.Gitlab.project_mergerequests`
+
+* GitLab API: https://docs.gitlab.com/ce/api/merge_requests.html
 
 Examples
 --------
@@ -20,8 +37,8 @@ List MRs for a project:
 
 You can filter and sort the returned list with the following parameters:
 
-* ``iid``: iid (unique ID for the project) of the MR
-* ``state``: state of the MR. It can be one of ``all``, ``merged``, '``opened``
+* ``iid``: iid (unique ID for the project) of the MR (v3 API)
+* ``state``: state of the MR. It can be one of ``all``, ``merged``, ``opened``
   or ``closed``
 * ``order_by``: sort by ``created_at`` or ``updated_at``
 * ``sort``: sort order (``asc`` or ``desc``)
diff --git a/docs/gl_objects/namespaces.rst b/docs/gl_objects/namespaces.rst
index 1819180..0dabdd9 100644
--- a/docs/gl_objects/namespaces.rst
+++ b/docs/gl_objects/namespaces.rst
@@ -2,11 +2,25 @@
 Namespaces
 ##########
 
-Use :class:`~gitlab.objects.Namespace` objects to manipulate namespaces. The
-:attr:`gitlab.Gitlab.namespaces` manager objects provides helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Namespace`
+  + :class:`gitlab.v4.objects.NamespaceManager`
+  + :attr:`gitlab.Gitlab.namespaces`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Namespace`
+  + :class:`gitlab.v3.objects.NamespaceManager`
+  + :attr:`gitlab.Gitlab.namespaces`
+
+* GitLab API: https://docs.gitlab.com/ce/api/namespaces.html
 
 Examples
-========
+--------
 
 List namespaces:
 
diff --git a/docs/gl_objects/notifications.rst b/docs/gl_objects/notifications.rst
index 472f710..a7310f3 100644
--- a/docs/gl_objects/notifications.rst
+++ b/docs/gl_objects/notifications.rst
@@ -5,22 +5,44 @@ Notification settings
 You can define notification settings globally, for groups and for projects.
 Valid levels are defined as constants:
 
-* ``NOTIFICATION_LEVEL_DISABLED``
-* ``NOTIFICATION_LEVEL_PARTICIPATING``
-* ``NOTIFICATION_LEVEL_WATCH``
-* ``NOTIFICATION_LEVEL_GLOBAL``
-* ``NOTIFICATION_LEVEL_MENTION``
-* ``NOTIFICATION_LEVEL_CUSTOM``
+* ``gitlab.NOTIFICATION_LEVEL_DISABLED``
+* ``gitlab.NOTIFICATION_LEVEL_PARTICIPATING``
+* ``gitlab.NOTIFICATION_LEVEL_WATCH``
+* ``gitlab.NOTIFICATION_LEVEL_GLOBAL``
+* ``gitlab.NOTIFICATION_LEVEL_MENTION``
+* ``gitlab.NOTIFICATION_LEVEL_CUSTOM``
 
 You get access to fine-grained settings if you use the
 ``NOTIFICATION_LEVEL_CUSTOM`` level.
 
-* Object classes: :class:`gitlab.objects.NotificationSettings` (global),
-  :class:`gitlab.objects.GroupNotificationSettings` (groups) and
-  :class:`gitlab.objects.ProjectNotificationSettings` (projects)
-* Manager objects: :attr:`gitlab.Gitlab.notificationsettings` (global),
-  :attr:`gitlab.objects.Group.notificationsettings` (groups) and
-  :attr:`gitlab.objects.Project.notificationsettings` (projects)
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.NotificationSettings`
+  + :class:`gitlab.v4.objects.NotificationSettingsManager`
+  + :attr:`gitlab.Gitlab.notificationsettings`
+  + :class:`gitlab.v4.objects.GroupNotificationSettings`
+  + :class:`gitlab.v4.objects.GroupNotificationSettingsManager`
+  + :attr:`gitlab.v4.objects.Group.notificationsettings`
+  + :class:`gitlab.v4.objects.ProjectNotificationSettings`
+  + :class:`gitlab.v4.objects.ProjectNotificationSettingsManager`
+  + :attr:`gitlab.v4.objects.Project.notificationsettings`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.NotificationSettings`
+  + :class:`gitlab.v3.objects.NotificationSettingsManager`
+  + :attr:`gitlab.Gitlab.notificationsettings`
+  + :class:`gitlab.v3.objects.GroupNotificationSettings`
+  + :class:`gitlab.v3.objects.GroupNotificationSettingsManager`
+  + :attr:`gitlab.v3.objects.Group.notificationsettings`
+  + :class:`gitlab.v3.objects.ProjectNotificationSettings`
+  + :class:`gitlab.v3.objects.ProjectNotificationSettingsManager`
+  + :attr:`gitlab.v3.objects.Project.notificationsettings`
+
+* GitLab API: https://docs.gitlab.com/ce/api/notification_settings.html
 
 Examples
 --------
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
index 428f357..131f43c 100644
--- a/docs/gl_objects/projects.py
+++ b/docs/gl_objects/projects.py
@@ -48,8 +48,6 @@ project.delete()
 # end delete
 
 # fork
-fork = gl.project_forks.create({}, project_id=1)
-# or
 fork = project.forks.create({})
 
 # fork to a specific namespace
@@ -78,28 +76,18 @@ project.events.list()
 # end events list
 
 # members list
-members = gl.project_members.list()
-# or
 members = project.members.list()
 # end members list
 
 # members search
-members = gl.project_members.list(query='foo')
-# or
 members = project.members.list(query='bar')
 # end members search
 
 # members get
-member = gl.project_members.get(1)
-# or
 member = project.members.get(1)
 # end members get
 
 # members add
-member = gl.project_members.create({'user_id': user.id, 'access_level':
-                                    gitlab.DEVELOPER_ACCESS},
-                                   project_id=1)
-# or
 member = project.members.create({'user_id': user.id, 'access_level':
                                  gitlab.DEVELOPER_ACCESS})
 # end members add
@@ -110,8 +98,6 @@ member.save()
 # end members update
 
 # members delete
-gl.project_members.delete(user.id, project_id=1)
-# or
 project.members.delete(user.id)
 # or
 member.delete()
@@ -122,14 +108,10 @@ project.share(group.id, gitlab.DEVELOPER_ACCESS)
 # end share
 
 # hook list
-hooks = gl.project_hooks.list(project_id=1)
-# or
 hooks = project.hooks.list()
 # end hook list
 
 # hook get
-hook = gl.project_hooks.get(1, project_id=1)
-# or
 hook = project.hooks.get(1)
 # end hook get
 
@@ -147,8 +129,6 @@ hook.save()
 # end hook update
 
 # hook delete
-gl.project_hooks.delete(1, project_id=1)
-# or
 project.hooks.delete(1)
 # or
 hook.delete()
@@ -199,9 +179,6 @@ contributors = project.repository_contributors()
 # end repository contributors
 
 # files get
-f = gl.project_files.get(file_path='README.rst', ref='master',
-                         project_id=1)
-# or
 f = project.files.get(file_path='README.rst', ref='master')
 
 # get the base64 encoded content
@@ -212,12 +189,13 @@ print(f.decode())
 # end files get
 
 # files create
-f = gl.project_files.create({'file_path': 'testfile',
-                             'branch_name': 'master',
-                             'content': file_content,
-                             'commit_message': 'Create testfile'},
-                            project_id=1)
-# or
+# v4
+f = project.files.create({'file_path': 'testfile',
+                          'branch': 'master',
+                          'content': file_content,
+                          'commit_message': 'Create testfile'})
+
+# v3
 f = project.files.create({'file_path': 'testfile',
                           'branch_name': 'master',
                           'content': file_content,
@@ -226,50 +204,33 @@ f = project.files.create({'file_path': 'testfile',
 
 # files update
 f.content = 'new content'
-f.save(branch_name='master', commit_message='Update testfile')
+f.save(branch'master', commit_message='Update testfile')  # v4
+f.save(branch_name='master', commit_message='Update testfile')  # v3
 
 # or for binary data
 # Note: decode() is required with python 3 for data serialization. You can omit
 # it with python 2
 f.content = base64.b64encode(open('image.png').read()).decode()
-f.save(branch_name='master', commit_message='Update testfile', encoding='base64')
+f.save(branch='master', commit_message='Update testfile', encoding='base64')
 # end files update
 
 # files delete
-gl.project_files.delete({'file_path': 'testfile',
-                         'branch_name': 'master',
-                         'commit_message': 'Delete testfile'},
-                        project_id=1)
-# or
-project.files.delete({'file_path': 'testfile',
-                      'branch_name': 'master',
-                      'commit_message': 'Delete testfile'})
-# or
 f.delete(commit_message='Delete testfile')
 # end files delete
 
 # tags list
-tags = gl.project_tags.list(project_id=1)
-# or
 tags = project.tags.list()
 # end tags list
 
 # tags get
-tag = gl.project_tags.list('1.0', project_id=1)
-# or
 tags = project.tags.list('1.0')
 # end tags get
 
 # tags create
-tag = gl.project_tags.create({'tag_name': '1.0', 'ref': 'master'},
-                             project_id=1)
-# or
 tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'})
 # end tags create
 
 # tags delete
-gl.project_tags.delete('1.0', project_id=1)
-# or
 project.tags.delete('1.0')
 # or
 tag.delete()
@@ -280,25 +241,14 @@ tag.set_release_description('awesome v1.0 release')
 # end tags release
 
 # snippets list
-snippets = gl.project_snippets.list(project_id=1)
-# or
 snippets = project.snippets.list()
 # end snippets list
 
 # snippets get
-snippet = gl.project_snippets.list(snippet_id, project_id=1)
-# or
 snippets = project.snippets.list(snippet_id)
 # end snippets get
 
 # snippets create
-snippet = gl.project_snippets.create({'title': 'sample 1',
-                                      'file_name': 'foo.py',
-                                      'code': 'import gitlab',
-                                      'visibility_level':
-                                      gitlab.VISIBILITY_PRIVATE},
-                                     project_id=1)
-# or
 snippet = project.snippets.create({'title': 'sample 1',
                                    'file_name': 'foo.py',
                                    'code': 'import gitlab',
@@ -316,43 +266,24 @@ snippet.save
 # end snippets update
 
 # snippets delete
-gl.project_snippets.delete(snippet_id, project_id=1)
-# or
 project.snippets.delete(snippet_id)
 # or
 snippet.delete()
 # end snippets delete
 
 # notes list
-i_notes = gl.project_issue_notes.list(project_id=1, issue_id=2)
-mr_notes = gl.project_mergerequest_notes.list(project_id=1, merge_request_id=2)
-s_notes = gl.project_snippet_notes.list(project_id=1, snippet_id=2)
-# or
 i_notes = issue.notes.list()
 mr_notes = mr.notes.list()
 s_notes = snippet.notes.list()
 # end notes list
 
 # notes get
-i_notes = gl.project_issue_notes.get(note_id, project_id=1, issue_id=2)
-mr_notes = gl.project_mergerequest_notes.get(note_id, project_id=1,
-                                             merge_request_id=2)
-s_notes = gl.project_snippet_notes.get(note_id, project_id=1, snippet_id=2)
-# or
 i_note = issue.notes.get(note_id)
 mr_note = mr.notes.get(note_id)
 s_note = snippet.notes.get(note_id)
 # end notes get
 
 # notes create
-i_note = gl.project_issue_notes.create({'body': 'note content'},
-                                       project_id=1, issue_id=2)
-mr_note = gl.project_mergerequest_notes.create({'body': 'note content'}
-                                               project_id=1,
-                                               merge_request_id=2)
-s_note = gl.project_snippet_notes.create({'body': 'note content'},
-                                          project_id=1, snippet_id=2)
-# or
 i_note = issue.notes.create({'body': 'note content'})
 mr_note = mr.notes.create({'body': 'note content'})
 s_note = snippet.notes.create({'body': 'note content'})
@@ -368,8 +299,6 @@ note.delete()
 # end notes delete
 
 # service get
-service = gl.project_services.get(service_name='asana', project_id=1)
-# or
 service = project.services.get(service_name='asana', project_id=1)
 # display it's status (enabled/disabled)
 print(service.active)
@@ -389,20 +318,14 @@ service.delete()
 # end service delete
 
 # pipeline list
-pipelines = gl.project_pipelines.list(project_id=1)
-# or
 pipelines = project.pipelines.list()
 # end pipeline list
 
 # pipeline get
-pipeline = gl.project_pipelines.get(pipeline_id, project_id=1)
-# or
 pipeline = project.pipelines.get(pipeline_id)
 # end pipeline get
 
 # pipeline create
-pipeline = gl.project_pipelines.create({'project_id': 1, 'ref': 'master'})
-# or
 pipeline = project.pipelines.create({'ref': 'master'})
 # end pipeline create
 
@@ -415,14 +338,10 @@ pipeline.cancel()
 # end pipeline cancel
 
 # boards list
-boards = gl.project_boards.list(project_id=1)
-# or
 boards = project.boards.list()
 # end boards list
 
 # boards get
-board = gl.project_boards.get(board_id, project_id=1)
-# or
 board = project.boards.get(board_id)
 # end boards get
 
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index 300b848..4a8a0ad 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -2,11 +2,28 @@
 Projects
 ########
 
-Use :class:`~gitlab.objects.Project` objects to manipulate projects. The
-:attr:`gitlab.Gitlab.projects` manager objects provides helper functions.
+Projects
+========
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Project`
+  + :class:`gitlab.v4.objects.ProjectManager`
+  + :attr:`gitlab.Gitlab.projects`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Project`
+  + :class:`gitlab.v3.objects.ProjectManager`
+  + :attr:`gitlab.Gitlab.projects`
+
+* GitLab API: https://docs.gitlab.com/ce/api/projects.html
 
 Examples
-========
+--------
 
 List projects:
 
@@ -97,11 +114,6 @@ Archive/unarchive a project:
    Previous versions used ``archive_`` and ``unarchive_`` due to a naming issue,
    they have been deprecated but not yet removed.
 
-Repository
-----------
-
-The following examples show how you can manipulate the project code repository.
-
 List the repository tree:
 
 .. literalinclude:: projects.py
@@ -148,10 +160,29 @@ Get a list of contributors for the repository:
    :start-after: # repository contributors
    :end-before: # end repository contributors
 
-Files
------
+Project files
+=============
+
+Reference
+---------
+
+* v4 API:
 
-The following examples show how you can manipulate the project files.
+  + :class:`gitlab.v4.objects.ProjectFile`
+  + :class:`gitlab.v4.objects.ProjectFileManager`
+  + :attr:`gitlab.v4.objects.Project.files`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectFile`
+  + :class:`gitlab.v3.objects.ProjectFileManager`
+  + :attr:`gitlab.v3.objects.Project.files`
+  + :attr:`gitlab.Gitlab.project_files`
+
+* GitLab API: https://docs.gitlab.com/ce/api/repository_files.html
+
+Examples
+--------
 
 Get a file:
 
@@ -178,12 +209,29 @@ Delete a file:
    :start-after: # files delete
    :end-before: # end files delete
 
-Tags
-----
+Project tags
+============
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectTag`
+  + :class:`gitlab.v4.objects.ProjectTagManager`
+  + :attr:`gitlab.v4.objects.Project.tags`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectTag`
+  + :class:`gitlab.v3.objects.ProjectTagManager`
+  + :attr:`gitlab.v3.objects.Project.tags`
+  + :attr:`gitlab.Gitlab.project_tags`
 
-Use :class:`~gitlab.objects.ProjectTag` objects to manipulate tags. The
-:attr:`gitlab.Gitlab.project_tags` and :attr:`Project.tags
-<gitlab.objects.Project.tags>` manager objects provide helper functions.
+* GitLab API: https://docs.gitlab.com/ce/api/tags.html
+
+Examples
+--------
 
 List the project tags:
 
@@ -217,12 +265,35 @@ Delete a tag:
 
 .. _project_snippets:
 
-Snippets
---------
+Project snippets
+================
 
-Use :class:`~gitlab.objects.ProjectSnippet` objects to manipulate snippets. The
-:attr:`gitlab.Gitlab.project_snippets` and :attr:`Project.snippets
-<gitlab.objects.Project.snippets>` manager objects provide helper functions.
+The snippet visibility can be definied using the following constants:
+
+* ``gitlab.VISIBILITY_PRIVATE``
+* ``gitlab.VISIBILITY_INTERNAL``
+* ``gitlab.VISIBILITY_PUBLIC``
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectSnippet`
+  + :class:`gitlab.v4.objects.ProjectSnippetManager`
+  + :attr:`gitlab.v4.objects.Project.files`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectSnippet`
+  + :class:`gitlab.v3.objects.ProjectSnippetManager`
+  + :attr:`gitlab.v3.objects.Project.files`
+  + :attr:`gitlab.Gitlab.project_files`
+
+* GitLab API: https://docs.gitlab.com/ce/api/project_snippets.html
+
+Examples
+--------
 
 List the project snippets:
 
@@ -266,9 +337,9 @@ Delete a snippet:
    :end-before: # end snippets delete
 
 Notes
------
+=====
 
-You can manipulate notes (comments) on the following resources:
+You can manipulate notes (comments) on the issues, merge requests and snippets.
 
 * :class:`~gitlab.objects.ProjectIssue` with
   :class:`~gitlab.objects.ProjectIssueNote`
@@ -277,6 +348,60 @@ You can manipulate notes (comments) on the following resources:
 * :class:`~gitlab.objects.ProjectSnippet` with
   :class:`~gitlab.objects.ProjectSnippetNote`
 
+Reference
+---------
+
+* v4 API:
+
+  Issues:
+
+  + :class:`gitlab.v4.objects.ProjectIssueNote`
+  + :class:`gitlab.v4.objects.ProjectIssueNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectIssue.notes`
+
+  MergeRequests:
+
+  + :class:`gitlab.v4.objects.ProjectMergeRequestNote`
+  + :class:`gitlab.v4.objects.ProjectMergeRequestNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectMergeRequest.notes`
+
+  Snippets:
+
+  + :class:`gitlab.v4.objects.ProjectSnippetNote`
+  + :class:`gitlab.v4.objects.ProjectSnippetNoteManager`
+  + :attr:`gitlab.v4.objects.ProjectSnippet.notes`
+
+* v3 API:
+
+  Issues:
+
+  + :class:`gitlab.v3.objects.ProjectIssueNote`
+  + :class:`gitlab.v3.objects.ProjectIssueNoteManager`
+  + :attr:`gitlab.v3.objects.ProjectIssue.notes`
+  + :attr:`gitlab.v3.objects.Project.issue_notes`
+  + :attr:`gitlab.Gitlab.project_issue_notes`
+
+  MergeRequests:
+
+  + :class:`gitlab.v3.objects.ProjectMergeRequestNote`
+  + :class:`gitlab.v3.objects.ProjectMergeRequestNoteManager`
+  + :attr:`gitlab.v3.objects.ProjectMergeRequest.notes`
+  + :attr:`gitlab.v3.objects.Project.mergerequest_notes`
+  + :attr:`gitlab.Gitlab.project_mergerequest_notes`
+
+  Snippets:
+
+  + :class:`gitlab.v3.objects.ProjectSnippetNote`
+  + :class:`gitlab.v3.objects.ProjectSnippetNoteManager`
+  + :attr:`gitlab.v3.objects.ProjectSnippet.notes`
+  + :attr:`gitlab.v3.objects.Project.snippet_notes`
+  + :attr:`gitlab.Gitlab.project_snippet_notes`
+
+* GitLab API: https://docs.gitlab.com/ce/api/repository_files.html
+
+Examples
+--------
+
 List the notes for a resource:
 
 .. literalinclude:: projects.py
@@ -307,12 +432,29 @@ Delete a note for a resource:
    :start-after: # notes delete
    :end-before: # end notes delete
 
-Events
-------
+Project events
+==============
 
-Use :class:`~gitlab.objects.ProjectEvent` objects to manipulate events. The
-:attr:`gitlab.Gitlab.project_events` and :attr:`Project.events
-<gitlab.objects.Project.events>` manager objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectEvent`
+  + :class:`gitlab.v4.objects.ProjectEventManager`
+  + :attr:`gitlab.v4.objects.Project.events`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectEvent`
+  + :class:`gitlab.v3.objects.ProjectEventManager`
+  + :attr:`gitlab.v3.objects.Project.events`
+  + :attr:`gitlab.Gitlab.project_events`
+
+* GitLab API: https://docs.gitlab.com/ce/api/repository_files.html
+
+Examples
+--------
 
 List the project events:
 
@@ -320,12 +462,29 @@ List the project events:
    :start-after: # events list
    :end-before: # end events list
 
-Team members
-------------
+Project members
+===============
 
-Use :class:`~gitlab.objects.ProjectMember` objects to manipulate projects
-members. The :attr:`gitlab.Gitlab.project_members` and :attr:`Project.members
-<gitlab.objects.Projects.members>` manager objects provide helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectMember`
+  + :class:`gitlab.v4.objects.ProjectMemberManager`
+  + :attr:`gitlab.v4.objects.Project.members`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectMember`
+  + :class:`gitlab.v3.objects.ProjectMemberManager`
+  + :attr:`gitlab.v3.objects.Project.members`
+  + :attr:`gitlab.Gitlab.project_members`
+
+* GitLab API: https://docs.gitlab.com/ce/api/members.html
+
+Examples
+--------
 
 List the project members:
 
@@ -369,12 +528,29 @@ Share the project with a group:
    :start-after: # share
    :end-before: # end share
 
-Hooks
------
+Project hooks
+=============
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectHook`
+  + :class:`gitlab.v4.objects.ProjectHookManager`
+  + :attr:`gitlab.v4.objects.Project.hooks`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectHook`
+  + :class:`gitlab.v3.objects.ProjectHookManager`
+  + :attr:`gitlab.v3.objects.Project.hooks`
+  + :attr:`gitlab.Gitlab.project_hooks`
+
+* GitLab API: https://docs.gitlab.com/ce/api/projects.html#hooks
 
-Use :class:`~gitlab.objects.ProjectHook` objects to manipulate projects
-hooks. The :attr:`gitlab.Gitlab.project_hooks` and :attr:`Project.hooks
-<gitlab.objects.Projects.hooks>` manager objects provide helper functions.
+Examples
+--------
 
 List the project hooks:
 
@@ -406,13 +582,29 @@ Delete a project hook:
    :start-after: # hook delete
    :end-before: # end hook delete
 
-Pipelines
+Project pipelines
+=================
+
+Reference
 ---------
 
-Use :class:`~gitlab.objects.ProjectPipeline` objects to manipulate projects
-pipelines. The :attr:`gitlab.Gitlab.project_pipelines` and
-:attr:`Project.services <gitlab.objects.Projects.pipelines>` manager objects
-provide helper functions.
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectPipeline`
+  + :class:`gitlab.v4.objects.ProjectPipelineManager`
+  + :attr:`gitlab.v4.objects.Project.pipelines`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectPipeline`
+  + :class:`gitlab.v3.objects.ProjectPipelineManager`
+  + :attr:`gitlab.v3.objects.Project.pipelines`
+  + :attr:`gitlab.Gitlab.project_pipelines`
+
+* GitLab API: https://docs.gitlab.com/ce/api/pipelines.html
+
+Examples
+--------
 
 List pipelines for a project:
 
@@ -444,13 +636,29 @@ Create a pipeline for a particular reference:
    :start-after: # pipeline create
    :end-before: # end pipeline create
 
-Services
---------
+Project Services
+================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectService`
+  + :class:`gitlab.v4.objects.ProjectServiceManager`
+  + :attr:`gitlab.v4.objects.Project.services`
+
+* v3 API:
 
-Use :class:`~gitlab.objects.ProjectService` objects to manipulate projects
-services. The :attr:`gitlab.Gitlab.project_services` and
-:attr:`Project.services <gitlab.objects.Projects.services>` manager objects
-provide helper functions.
+  + :class:`gitlab.v3.objects.ProjectService`
+  + :class:`gitlab.v3.objects.ProjectServiceManager`
+  + :attr:`gitlab.v3.objects.Project.services`
+  + :attr:`gitlab.Gitlab.project_services`
+
+* GitLab API: https://docs.gitlab.com/ce/api/services.html
+
+Exammples
+---------
 
 Get a service:
 
@@ -476,13 +684,34 @@ Disable a service:
    :start-after: # service delete
    :end-before: # end service delete
 
-Boards
-------
+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`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectBoard`
+  + :class:`gitlab.v3.objects.ProjectBoardManager`
+  + :attr:`gitlab.v3.objects.Project.boards`
+  + :attr:`gitlab.Gitlab.project_boards`
+
+* GitLab API: https://docs.gitlab.com/ce/api/boards.html
+
+Examples
+--------
+
 Get the list of existing boards for a project:
 
 .. literalinclude:: projects.py
@@ -495,8 +724,30 @@ Get a single board for a project:
    :start-after: # boards get
    :end-before: # end boards get
 
-Boards have lists of issues. Each list is defined by a
-:class:`~gitlab.objects.ProjectLabel` and a position in the board.
+Board lists
+===========
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectBoardList`
+  + :class:`gitlab.v4.objects.ProjectBoardListManager`
+  + :attr:`gitlab.v4.objects.Project.board_lists`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectBoardList`
+  + :class:`gitlab.v3.objects.ProjectBoardListManager`
+  + :attr:`gitlab.v3.objects.ProjectBoard.lists`
+  + :attr:`gitlab.v3.objects.Project.board_lists`
+  + :attr:`gitlab.Gitlab.project_board_lists`
+
+* GitLab API: https://docs.gitlab.com/ce/api/boards.html
+
+Examples
+--------
 
 List the issue lists for a board:
 
@@ -510,15 +761,14 @@ Get a single list:
    :start-after: # board lists get
    :end-before: # end board lists get
 
-Create a new list. Note that getting the label ID is broken at the moment (see
-https://gitlab.com/gitlab-org/gitlab-ce/issues/23448):
+Create a new list:
 
 .. literalinclude:: projects.py
    :start-after: # board lists create
    :end-before: # end board lists create
 
 Change a list position. The first list is at position 0. Moving a list will
-insert it at the given position and move the following lists up a position:
+set it at the given position and move the following lists up a position:
 
 .. literalinclude:: projects.py
    :start-after: # board lists update
diff --git a/docs/gl_objects/runners.py b/docs/gl_objects/runners.py
index 1a9cb82..93aca0d 100644
--- a/docs/gl_objects/runners.py
+++ b/docs/gl_objects/runners.py
@@ -24,19 +24,13 @@ runner.delete()
 # end delete
 
 # project list
-runners = gl.project_runners.list(project_id=1)
-# or
 runners = project.runners.list()
 # end project list
 
 # project enable
-p_runner = gl.project_runners.create({'runner_id': runner.id}, project_id=1)
-# or
 p_runner = project.runners.create({'runner_id': runner.id})
 # end project enable
 
 # project disable
-gl.project_runners.delete(runner.id)
-# or
 project.runners.delete(runner.id)
 # end project disable
diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst
index 02db9be..e26c8af 100644
--- a/docs/gl_objects/runners.rst
+++ b/docs/gl_objects/runners.rst
@@ -2,7 +2,7 @@
 Runners
 #######
 
-Runners are external process used to run CI jobs. They are deployed by the
+Runners are external processes used to run CI jobs. They are deployed by the
 administrator and registered to the GitLab instance.
 
 Shared runners are available for all projects. Specific runners are enabled for
@@ -11,8 +11,22 @@ a list of projects.
 Global runners (admin)
 ======================
 
-* Object class: :class:`~gitlab.objects.Runner`
-* Manager objects: :attr:`gitlab.Gitlab.runners`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Runner`
+  + :class:`gitlab.v4.objects.RunnerManager`
+  + :attr:`gitlab.Gitlab.runners`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Runner`
+  + :class:`gitlab.v3.objects.RunnerManager`
+  + :attr:`gitlab.Gitlab.runners`
+
+* GitLab API: https://docs.gitlab.com/ce/api/runners.html
 
 Examples
 --------
@@ -58,9 +72,23 @@ Remove a runner:
 Project runners
 ===============
 
-* Object class: :class:`~gitlab.objects.ProjectRunner`
-* Manager objects: :attr:`gitlab.Gitlab.runners`,
-  :attr:`gitlab.Gitlab.Project.runners`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectRunner`
+  + :class:`gitlab.v4.objects.ProjectRunnerManager`
+  + :attr:`gitlab.v4.objects.Project.runners`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectRunner`
+  + :class:`gitlab.v3.objects.ProjectRunnerManager`
+  + :attr:`gitlab.v3.objects.Project.runners`
+  + :attr:`gitlab.Gitlab.project_runners`
+
+* GitLab API: https://docs.gitlab.com/ce/api/runners.html
 
 Examples
 --------
diff --git a/docs/gl_objects/settings.rst b/docs/gl_objects/settings.rst
index 26f68c5..5f0e92f 100644
--- a/docs/gl_objects/settings.rst
+++ b/docs/gl_objects/settings.rst
@@ -2,9 +2,22 @@
 Settings
 ########
 
-Use :class:`~gitlab.objects.ApplicationSettings` objects to manipulate Gitlab
-settings. The :attr:`gitlab.Gitlab.settings` manager object provides helper
-functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ApplicationSettings`
+  + :class:`gitlab.v4.objects.ApplicationSettingsManager`
+  + :attr:`gitlab.Gitlab.settings`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ApplicationSettings`
+  + :class:`gitlab.v3.objects.ApplicationSettingsManager`
+  + :attr:`gitlab.Gitlab.settings`
+
+* GitLab API: https://docs.gitlab.com/ce/api/commits.html
 
 Examples
 --------
diff --git a/docs/gl_objects/sidekiq.rst b/docs/gl_objects/sidekiq.rst
index a75a02d..593dda0 100644
--- a/docs/gl_objects/sidekiq.rst
+++ b/docs/gl_objects/sidekiq.rst
@@ -2,8 +2,20 @@
 Sidekiq metrics
 ###############
 
-Use the :attr:`gitlab.Gitlab.sideqik` manager object to access Gitlab Sidekiq
-server metrics.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.SidekiqManager`
+  + :attr:`gitlab.Gitlab.sidekiq`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.SidekiqManager`
+  + :attr:`gitlab.Gitlab.sidekiq`
+
+* GitLab API: https://docs.gitlab.com/ce/api/sidekiq_metrics.html
 
 Examples
 --------
diff --git a/docs/gl_objects/system_hooks.rst b/docs/gl_objects/system_hooks.rst
index 1d1804b..a9e9fee 100644
--- a/docs/gl_objects/system_hooks.rst
+++ b/docs/gl_objects/system_hooks.rst
@@ -2,8 +2,22 @@
 System hooks
 ############
 
-Use :class:`~gitlab.objects.Hook` objects to manipulate system hooks. The
-:attr:`gitlab.Gitlab.hooks` manager object provides helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Hook`
+  + :class:`gitlab.v4.objects.HookManager`
+  + :attr:`gitlab.Gitlab.hooks`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Hook`
+  + :class:`gitlab.v3.objects.HookManager`
+  + :attr:`gitlab.Gitlab.hooks`
+
+* GitLab API: https://docs.gitlab.com/ce/api/system_hooks.html
 
 Examples
 --------
diff --git a/docs/gl_objects/templates.py b/docs/gl_objects/templates.py
index 1bc97bb..0874dc7 100644
--- a/docs/gl_objects/templates.py
+++ b/docs/gl_objects/templates.py
@@ -24,3 +24,12 @@ gitlabciymls = gl.gitlabciymls.list()
 gitlabciyml = gl.gitlabciymls.get('Pelican')
 print(gitlabciyml.content)
 # end gitlabciyml get
+
+# dockerfile list
+dockerfiles = gl.dockerfiles.list()
+# end dockerfile list
+
+# dockerfile get
+dockerfile = gl.dockerfiles.get('Python')
+print(dockerfile.content)
+# end dockerfile get
diff --git a/docs/gl_objects/templates.rst b/docs/gl_objects/templates.rst
index 1ce429d..c43b7ae 100644
--- a/docs/gl_objects/templates.rst
+++ b/docs/gl_objects/templates.rst
@@ -7,12 +7,27 @@ You can request templates for different type of files:
 * License files
 * .gitignore files
 * GitLab CI configuration files
+* Dockerfiles
 
 License templates
 =================
 
-* Object class: :class:`~gitlab.objects.License`
-* Manager object: :attr:`gitlab.Gitlab.licenses`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.License`
+  + :class:`gitlab.v4.objects.LicenseManager`
+  + :attr:`gitlab.Gitlab.licenses`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.License`
+  + :class:`gitlab.v3.objects.LicenseManager`
+  + :attr:`gitlab.Gitlab.licenses`
+
+* GitLab API: https://docs.gitlab.com/ce/api/templates/licenses.html
 
 Examples
 --------
@@ -32,8 +47,22 @@ Generate a license content for a project:
 .gitignore templates
 ====================
 
-* Object class: :class:`~gitlab.objects.Gitignore`
-* Manager object: :attr:`gitlab.Gitlab.gitognores`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Gitignore`
+  + :class:`gitlab.v4.objects.GitignoreManager`
+  + :attr:`gitlab.Gitlab.gitignores`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Gitignore`
+  + :class:`gitlab.v3.objects.GitignoreManager`
+  + :attr:`gitlab.Gitlab.gitignores`
+
+* GitLab API: https://docs.gitlab.com/ce/api/templates/gitignores.html
 
 Examples
 --------
@@ -53,8 +82,22 @@ Get a gitignore template:
 GitLab CI templates
 ===================
 
-* Object class: :class:`~gitlab.objects.Gitlabciyml`
-* Manager object: :attr:`gitlab.Gitlab.gitlabciymls`
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Gitlabciyml`
+  + :class:`gitlab.v4.objects.GitlabciymlManager`
+  + :attr:`gitlab.Gitlab.gitlabciymls`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.Gitlabciyml`
+  + :class:`gitlab.v3.objects.GitlabciymlManager`
+  + :attr:`gitlab.Gitlab.gitlabciymls`
+
+* GitLab API: https://docs.gitlab.com/ce/api/templates/gitlab_ci_ymls.html
 
 Examples
 --------
@@ -70,3 +113,32 @@ Get a GitLab CI template:
 .. literalinclude:: templates.py
    :start-after: # gitlabciyml get
    :end-before: # end gitlabciyml get
+
+Dockerfile templates
+====================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Dockerfile`
+  + :class:`gitlab.v4.objects.DockerfileManager`
+  + :attr:`gitlab.Gitlab.gitlabciymls`
+
+* GitLab API: Not documented.
+
+Examples
+--------
+
+List known Dockerfile templates:
+
+.. literalinclude:: templates.py
+   :start-after: # dockerfile list
+   :end-before: # end dockerfile list
+
+Get a Dockerfile template:
+
+.. literalinclude:: templates.py
+   :start-after: # dockerfile get
+   :end-before: # end dockerfile get