[docs] Rework the examples pages

* Get rid of the .py files and bring all the python examples in the RST
files
* Fix a few things

49 files changed, 697 insertions, 2319 deletions

diff --git a/docs/gl_objects/access_requests.py b/docs/gl_objects/access_requests.py
deleted file mode 100644
index 9df639d..0000000
--- a/docs/gl_objects/access_requests.py
+++ /dev/null
@@ -1,26 +0,0 @@
-# list
-p_ars = project.accessrequests.list()
-g_ars = group.accessrequests.list()
-# end list
-
-# get
-p_ar = project.accessrequests.get(user_id)
-g_ar = group.accessrequests.get(user_id)
-# end get
-
-# create
-p_ar = project.accessrequests.create({})
-g_ar = group.accessrequests.create({})
-# end create
-
-# approve
-ar.approve()  # defaults to DEVELOPER level
-ar.approve(access_level=gitlab.MASTER_ACCESS)  # explicitly set access level
-# end approve
-
-# delete
-project.accessrequests.delete(user_id)
-group.accessrequests.delete(user_id)
-# or
-ar.delete()
-# end delete
diff --git a/docs/gl_objects/access_requests.rst b/docs/gl_objects/access_requests.rst
index f64e795..9a147c1 100644
--- a/docs/gl_objects/access_requests.rst
+++ b/docs/gl_objects/access_requests.rst
@@ -25,48 +25,29 @@ References
   + :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
 --------
 
-List access requests from projects and groups:
-
-.. literalinclude:: access_requests.py
-   :start-after: # list
-   :end-before: # end list
-
-Get a single request:
+List access requests from projects and groups::
 
-.. literalinclude:: access_requests.py
-   :start-after: # get
-   :end-before: # end get
+    p_ars = project.accessrequests.list()
+    g_ars = group.accessrequests.list()
 
-Create an access request:
+Create an access request::
 
-.. literalinclude:: access_requests.py
-   :start-after: # create
-   :end-before: # end create
+    p_ar = project.accessrequests.create({})
+    g_ar = group.accessrequests.create({})
 
-Approve an access request:
+Approve an access request::
 
-.. literalinclude:: access_requests.py
-   :start-after: # approve
-   :end-before: # end approve
+    ar.approve()  # defaults to DEVELOPER level
+    ar.approve(access_level=gitlab.MASTER_ACCESS)  # explicitly set access level
 
-Deny (delete) an access request:
+Deny (delete) an access request::
 
-.. literalinclude:: access_requests.py
-   :start-after: # delete
-   :end-before: # end delete
+    project.accessrequests.delete(user_id)
+    group.accessrequests.delete(user_id)
+    # or
+    ar.delete()
diff --git a/docs/gl_objects/branches.py b/docs/gl_objects/branches.py
deleted file mode 100644
index 431e09d..0000000
--- a/docs/gl_objects/branches.py
+++ /dev/null
@@ -1,46 +0,0 @@
-# list
-branches = project.branches.list()
-# end list
-
-# get
-branch = project.branches.get('master')
-# end get
-
-# create
-# v4
-branch = project.branches.create({'branch': 'feature1',
-                                  'ref': 'master'})
-
-#v3
-branch = project.branches.create({'branch_name': 'feature1',
-                                  'ref': 'master'})
-# end create
-
-# delete
-project.branches.delete('feature1')
-# or
-branch.delete()
-# end delete
-
-# protect
-branch.protect()
-branch.unprotect()
-# end protect
-
-# p_branch list
-p_branches = project.protectedbranches.list()
-# end p_branch list
-
-# p_branch get
-p_branch = project.protectedbranches.get('master')
-# end p_branch get
-
-# p_branch create
-p_branch = project.protectedbranches.create({'name': '*-stable'})
-# end p_branch create
-
-# p_branch delete
-project.protectedbranches.delete('*-stable')
-# or
-p_branch.delete()
-# end p_branch delete
diff --git a/docs/gl_objects/branches.rst b/docs/gl_objects/branches.rst
index 279ca0c..15f2b5c 100644
--- a/docs/gl_objects/branches.rst
+++ b/docs/gl_objects/branches.rst
@@ -11,46 +11,34 @@ References
   + :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:
+Get the list of branches for a repository::
 
-.. literalinclude:: branches.py
-   :start-after: # list
-   :end-before: # end list
+    branches = project.branches.list()
 
-Get a single repository branch:
+Get a single repository branch::
 
-.. literalinclude:: branches.py
-   :start-after: # get
-   :end-before: # end get
+    branch = project.branches.get('master')
 
-Create a repository branch:
+Create a repository branch::
 
-.. literalinclude:: branches.py
-   :start-after: # create
-   :end-before: # end create
+    branch = project.branches.create({'branch': 'feature1',
+                                      'ref': 'master'})
 
-Delete a repository branch:
+Delete a repository branch::
 
-.. literalinclude:: branches.py
-   :start-after: # delete
-   :end-before: # end delete
+    project.branches.delete('feature1')
+    # or
+    branch.delete()
 
-Protect/unprotect a repository branch:
+Protect/unprotect a repository branch::
 
-.. literalinclude:: branches.py
-   :start-after: # protect
-   :end-before: # end protect
+    branch.protect()
+    branch.unprotect()
 
 .. note::
 
diff --git a/docs/gl_objects/builds.rst b/docs/gl_objects/builds.rst
index d5f851c..089aab7 100644
--- a/docs/gl_objects/builds.rst
+++ b/docs/gl_objects/builds.rst
@@ -1,9 +1,6 @@
-##########################
-Pipelines, Builds and Jobs
-##########################
-
-Build and job are two classes representing the same object. Builds are used in
-v3 API, jobs in v4 API.
+##################
+Pipelines and Jobs
+##################
 
 Project pipelines
 =================
@@ -19,13 +16,6 @@ Reference
   + :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
@@ -66,13 +56,6 @@ Reference
   + :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
@@ -88,8 +71,7 @@ Get a trigger::
 
 Create a trigger::
 
-    trigger = project.triggers.create({}) # v3
-    trigger = project.triggers.create({'description': 'mytrigger'}) # v4
+    trigger = project.triggers.create({'description': 'mytrigger'})
 
 Remove a trigger::
 
@@ -190,13 +172,6 @@ Reference
   + :class:`gitlab.v4.objects.GroupVariableManager`
   + :attr:`gitlab.v4.objects.Group.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
@@ -232,11 +207,11 @@ Remove a variable::
     # or
     var.delete()
 
-Builds/Jobs
-===========
+Jobs
+====
 
-Builds/Jobs are associated to projects, pipelines and commits. They provide
-information on the builds/jobs that have been run, and methods to manipulate
+Jobs are associated to projects, pipelines and commits. They provide
+information on the jobs that have been run, and methods to manipulate
 them.
 
 Reference
@@ -248,13 +223,6 @@ Reference
   + :class:`gitlab.v4.objects.ProjectJobManager`
   + :attr:`gitlab.v4.objects.Project.jobs`
 
-* v3 API
-
-  + :class:`gitlab.v3.objects.ProjectJob`
-  + :class:`gitlab.v3.objects.ProjectJobManager`
-  + :attr:`gitlab.v3.objects.Project.jobs`
-  + :attr:`gitlab.Gitlab.project_jobs`
-
 * GitLab API: https://docs.gitlab.com/ce/api/jobs.html
 
 Examples
@@ -268,23 +236,13 @@ job::
 
 List jobs for the project::
 
-    builds = project.builds.list()  # v3
-    jobs = project.jobs.list()  # v4
-
-To list builds for a specific commit, create a
-:class:`~gitlab.v3.objects.ProjectCommit` object and use its
-:attr:`~gitlab.v3.objects.ProjectCommit.builds` method (v3 only)::
-
-    # v3 only
-    commit = gl.project_commits.get(commit_sha, project_id=1)
-    builds = commit.builds()
+    jobs = project.jobs.list()
 
 To list builds for a specific pipeline or get a single job within a specific
 pipeline, create a
 :class:`~gitlab.v4.objects.ProjectPipeline` object and use its
-:attr:`~gitlab.v4.objects.ProjectPipeline.jobs` method (v4 only)::
+:attr:`~gitlab.v4.objects.ProjectPipeline.jobs` method::
 
-    # v4 only
     project = gl.projects.get(project_id)
     pipeline = project.pipelines.get(pipeline_id)
     jobs = pipeline.jobs.list()  # gets all jobs in pipeline
@@ -292,8 +250,7 @@ pipeline, create a
 
 Get a job::
 
-    project.builds.get(build_id)  # v3
-    project.jobs.get(job_id)  # v4
+    project.jobs.get(job_id)
 
 Get the artifacts of a job::
 
diff --git a/docs/gl_objects/commits.py b/docs/gl_objects/commits.py
deleted file mode 100644
index 88d0095..0000000
--- a/docs/gl_objects/commits.py
+++ /dev/null
@@ -1,68 +0,0 @@
-# list
-commits = project.commits.list()
-# end list
-
-# filter list
-commits = project.commits.list(ref_name='my_branch')
-commits = project.commits.list(since='2016-01-01T00:00:00Z')
-# end filter list
-
-# create
-# See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
-# for actions detail
-data = {
-    'branch_name': 'master',  # v3
-    'branch': 'master',  # v4
-    'commit_message': 'blah blah blah',
-    'actions': [
-        {
-            'action': 'create',
-            'file_path': 'README.rst',
-            'content': open('path/to/file.rst').read(),
-        },
-        {
-            # Binary files need to be base64 encoded
-            'action': 'create',
-            'file_path': 'logo.png',
-            'content': base64.b64encode(open('logo.png').read()),
-            'encoding': 'base64',
-        }
-    ]
-}
-
-commit = project.commits.create(data)
-# end create
-
-# get
-commit = project.commits.get('e3d5a71b')
-# end get
-
-# diff
-diff = commit.diff()
-# end diff
-
-# cherry
-commit.cherry_pick(branch='target_branch')
-# end cherry
-
-# comments list
-comments = commit.comments.list()
-# end comments list
-
-# comments create
-# Global comment
-commit = commit.comments.create({'note': 'This is a nice comment'})
-# Comment on a line in a file (on the new version of the file)
-commit = commit.comments.create({'note': 'This is another comment',
-                                 'line': 12,
-                                 'line_type': 'new',
-                                 'path': 'README.rst'})
-# end comments create
-
-# statuses list
-statuses = commit.statuses.list()
-# end statuses list
-
-# statuses set
-commit.statuses.create({'state': 'success'})
-# end statuses set
diff --git a/docs/gl_objects/commits.rst b/docs/gl_objects/commits.rst
index 8a32709..22e23f6 100644
--- a/docs/gl_objects/commits.rst
+++ b/docs/gl_objects/commits.rst
@@ -14,60 +14,56 @@ Reference
   + :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
-
-.. warning::
-
-   Pagination starts at page 0 in v3, but starts at page 1 in v4 (like all the
-   v4 endpoints).
-
-
 Examples
 --------
 
-List the commits for a project:
+List the commits for a project::
 
-.. literalinclude:: commits.py
-   :start-after: # list
-   :end-before: # end list
+    commits = project.commits.list()
 
 You can use the ``ref_name``, ``since`` and ``until`` filters to limit the
-results:
+results::
+
+    commits = project.commits.list(ref_name='my_branch')
+    commits = project.commits.list(since='2016-01-01T00:00:00Z')
 
-.. literalinclude:: commits.py
-   :start-after: # filter list
-   :end-before: # end filter list
+Create a commit::
 
-Create a commit:
+    # See https://docs.gitlab.com/ce/api/commits.html#create-a-commit-with-multiple-files-and-actions
+    # for actions detail
+    data = {
+        'branch_name': 'master',  # v3
+        'branch': 'master',  # v4
+        'commit_message': 'blah blah blah',
+        'actions': [
+            {
+                'action': 'create',
+                'file_path': 'README.rst',
+                'content': open('path/to/file.rst').read(),
+            },
+            {
+                # Binary files need to be base64 encoded
+                'action': 'create',
+                'file_path': 'logo.png',
+                'content': base64.b64encode(open('logo.png').read()),
+                'encoding': 'base64',
+            }
+        ]
+    }
 
-.. literalinclude:: commits.py
-   :start-after: # create
-   :end-before: # end create
+    commit = project.commits.create(data)
 
-Get a commit detail:
+Get a commit detail::
 
-.. literalinclude:: commits.py
-   :start-after: # get
-   :end-before: # end get
+    commit = project.commits.get('e3d5a71b')
 
-Get the diff for a commit:
+Get the diff for a commit::
 
-.. literalinclude:: commits.py
-   :start-after: # diff
-   :end-before: # end diff
+    diff = commit.diff()
 
-Cherry-pick a commit into another branch:
+Cherry-pick a commit into another branch::
 
-.. literalinclude:: commits.py
-   :start-after: # cherry
-   :end-before: # end cherry
+    commit.cherry_pick(branch='target_branch')
 
 Commit comments
 ===============
@@ -81,30 +77,24 @@ Reference
   + :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
 --------
 
-Get the comments for a commit:
+Get the comments for a commit::
 
-.. literalinclude:: commits.py
-   :start-after: # comments list
-   :end-before: # end comments list
+    comments = commit.comments.list()
 
-Add a comment on a commit:
+Add a comment on a commit::
 
-.. literalinclude:: commits.py
-   :start-after: # comments create
-   :end-before: # end comments create
+    # Global comment
+    commit = commit.comments.create({'note': 'This is a nice comment'})
+    # Comment on a line in a file (on the new version of the file)
+    commit = commit.comments.create({'note': 'This is another comment',
+                                     'line': 12,
+                                     'line_type': 'new',
+                                     'path': 'README.rst'})
 
 Commit status
 =============
@@ -118,27 +108,15 @@ Reference
   + :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
 --------
 
-Get the statuses for a commit:
+List the statuses for a commit::
 
-.. literalinclude:: commits.py
-   :start-after: # statuses list
-   :end-before: # end statuses list
+    statuses = commit.statuses.list()
 
-Change the status of a commit:
+Change the status of a commit::
 
-.. literalinclude:: commits.py
-   :start-after: # statuses set
-   :end-before: # end statuses set
+    commit.statuses.create({'state': 'success'})
diff --git a/docs/gl_objects/deploy_keys.py b/docs/gl_objects/deploy_keys.py
deleted file mode 100644
index ccdf30e..0000000
--- a/docs/gl_objects/deploy_keys.py
+++ /dev/null
@@ -1,35 +0,0 @@
-# global list
-keys = gl.deploykeys.list()
-# end global list
-
-# global get
-key = gl.deploykeys.get(key_id)
-# end global get
-
-# list
-keys = project.keys.list()
-# end list
-
-# get
-key = project.keys.get(key_id)
-# end get
-
-# create
-key = project.keys.create({'title': 'jenkins key',
-                           'key': open('/home/me/.ssh/id_rsa.pub').read()})
-# end create
-
-# delete
-key = project.keys.list(key_id)
-# or
-key.delete()
-# end delete
-
-# enable
-project.keys.enable(key_id)
-# end enable
-
-# disable
-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 a293d27..31e31a9 100644
--- a/docs/gl_objects/deploy_keys.rst
+++ b/docs/gl_objects/deploy_keys.rst
@@ -14,28 +14,14 @@ Reference
   + :class:`gitlab.v4.objects.DeployKeyManager`
   + :attr:`gitlab.Gitlab.deploykeys`
 
-* v3 API:
-
-  + :class:`gitlab.v3.objects.DeployKey`
-  + :class:`gitlab.v3.objects.DeployKeyManager`
-  + :attr:`gitlab.Gitlab.deploykeys`
-
 * GitLab API: https://docs.gitlab.com/ce/api/deploy_keys.html
 
 Examples
 --------
 
-List the deploy keys:
-
-.. literalinclude:: deploy_keys.py
-   :start-after: # global list
-   :end-before: # end global list
+List the deploy keys::
 
-Get a single deploy key:
-
-.. literalinclude:: deploy_keys.py
-   :start-after: # global get
-   :end-before: # end global get
+    keys = gl.deploykeys.list()
 
 Deploy keys for projects
 ========================
@@ -51,50 +37,34 @@ Reference
   + :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
 --------
 
-List keys for a project:
+List keys for a project::
 
-.. literalinclude:: deploy_keys.py
-   :start-after: # list
-   :end-before: # end list
+    keys = project.keys.list()
 
-Get a single deploy key:
+Get a single deploy key::
 
-.. literalinclude:: deploy_keys.py
-   :start-after: # get
-   :end-before: # end get
+    key = project.keys.get(key_id)
 
-Create a deploy key for a project:
+Create a deploy key for a project::
 
-.. literalinclude:: deploy_keys.py
-   :start-after: # create
-   :end-before: # end create
+    key = project.keys.create({'title': 'jenkins key',
+                               'key': open('/home/me/.ssh/id_rsa.pub').read()})
 
-Delete a deploy key for a project:
+Delete a deploy key for a project::
 
-.. literalinclude:: deploy_keys.py
-   :start-after: # delete
-   :end-before: # end delete
+    key = project.keys.list(key_id)
+    # or
+    key.delete()
 
-Enable a deploy key for a project:
+Enable a deploy key for a project::
 
-.. literalinclude:: deploy_keys.py
-   :start-after: # enable
-   :end-before: # end enable
+    project.keys.enable(key_id)
 
-Disable a deploy key for a project:
+Disable a deploy key for a project::
 
-.. literalinclude:: deploy_keys.py
-   :start-after: # disable
-   :end-before: # end disable
+    project_key.delete()
diff --git a/docs/gl_objects/deployments.py b/docs/gl_objects/deployments.py
deleted file mode 100644
index 5084b4d..0000000
--- a/docs/gl_objects/deployments.py
+++ /dev/null
@@ -1,7 +0,0 @@
-# list
-deployments = project.deployments.list()
-# end list
-
-# get
-deployment = project.deployments.get(deployment_id)
-# end get
diff --git a/docs/gl_objects/deployments.rst b/docs/gl_objects/deployments.rst
index 37e9468..333d497 100644
--- a/docs/gl_objects/deployments.rst
+++ b/docs/gl_objects/deployments.rst
@@ -11,26 +11,15 @@ Reference
   + :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
 --------
 
-List deployments for a project:
+List deployments for a project::
 
-.. literalinclude:: deployments.py
-   :start-after: # list
-   :end-before: # end list
+    deployments = project.deployments.list()
 
-Get a single deployment:
+Get a single deployment::
 
-.. literalinclude:: deployments.py
-   :start-after: # get
-   :end-before: # end get
+    deployment = project.deployments.get(deployment_id)
diff --git a/docs/gl_objects/environments.py b/docs/gl_objects/environments.py
deleted file mode 100644
index 3ca6fc1..0000000
--- a/docs/gl_objects/environments.py
+++ /dev/null
@@ -1,22 +0,0 @@
-# list
-environments = project.environments.list()
-# end list
-
-# get
-environment = project.environments.get(environment_id)
-# end get
-
-# create
-environment = project.environments.create({'name': 'production'})
-# end create
-
-# update
-environment.external_url = 'http://foo.bar.com'
-environment.save()
-# end update
-
-# delete
-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 d94c453..1867d24 100644
--- a/docs/gl_objects/environments.rst
+++ b/docs/gl_objects/environments.rst
@@ -11,44 +11,26 @@ Reference
   + :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
 --------
 
-List environments for a project:
-
-.. literalinclude:: environments.py
-   :start-after: # list
-   :end-before: # end list
-
-Get a single environment:
+List environments for a project::
 
-.. literalinclude:: environments.py
-   :start-after: # get
-   :end-before: # end get
+    environments = project.environments.list()
 
-Create an environment for a project:
+Create an environment for a project::
 
-.. literalinclude:: environments.py
-   :start-after: # create
-   :end-before: # end create
+    environment = project.environments.create({'name': 'production'})
 
-Update an environment for a project:
+Update an environment for a project::
 
-.. literalinclude:: environments.py
-   :start-after: # update
-   :end-before: # end update
+    environment.external_url = 'http://foo.bar.com'
+    environment.save()
 
-Delete an environment for a project:
+Delete an environment for a project::
 
-.. literalinclude:: environments.py
-   :start-after: # delete
-   :end-before: # end delete
+    environment = project.environments.delete(environment_id)
+    # or
+    environment.delete()
diff --git a/docs/gl_objects/events.rst b/docs/gl_objects/events.rst
index eef524f..8071b00 100644
--- a/docs/gl_objects/events.rst
+++ b/docs/gl_objects/events.rst
@@ -17,13 +17,6 @@ Reference
   + :class:`gitlab.v4.objects.UserEventManager`
   + :attr:`gitlab.v4.objects.User.events`
 
-* v3 API (projects events only):
-
-  + :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/events.html
 
 Examples
diff --git a/docs/gl_objects/groups.rst b/docs/gl_objects/groups.rst
index 493f5d0..d24e53c 100644
--- a/docs/gl_objects/groups.rst
+++ b/docs/gl_objects/groups.rst
@@ -14,12 +14,6 @@ Reference
   + :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
@@ -148,13 +142,6 @@ Reference
   + :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
 
 
diff --git a/docs/gl_objects/issues.py b/docs/gl_objects/issues.py
deleted file mode 100644
index fe77473..0000000
--- a/docs/gl_objects/issues.py
+++ /dev/null
@@ -1,95 +0,0 @@
-# list
-issues = gl.issues.list()
-# end list
-
-# filtered list
-open_issues = gl.issues.list(state='opened')
-closed_issues = gl.issues.list(state='closed')
-tagged_issues = gl.issues.list(labels=['foo', 'bar'])
-# end filtered list
-
-# group issues list
-issues = group.issues.list()
-# Filter using the state, labels and milestone parameters
-issues = group.issues.list(milestone='1.0', state='opened')
-# Order using the order_by and sort parameters
-issues = group.issues.list(order_by='created_at', sort='desc')
-# end group issues list
-
-# project issues list
-issues = project.issues.list()
-# Filter using the state, labels and milestone parameters
-issues = project.issues.list(milestone='1.0', state='opened')
-# Order using the order_by and sort parameters
-issues = project.issues.list(order_by='created_at', sort='desc')
-# end project issues list
-
-# project issues get
-issue = project.issues.get(issue_id)
-# end project issues get
-
-# project issues get from iid
-issue = project.issues.list(iid=issue_iid)[0]
-# end project issues get from iid
-
-# project issues create
-issue = project.issues.create({'title': 'I have a bug',
-                               'description': 'Something useful here.'})
-# end project issues create
-
-# project issue update
-issue.labels = ['foo', 'bar']
-issue.save()
-# end project issue update
-
-# project issue open_close
-# close an issue
-issue.state_event = 'close'
-issue.save()
-# reopen it
-issue.state_event = 'reopen'
-issue.save()
-# end project issue open_close
-
-# project issue delete
-project.issues.delete(issue_id)
-# pr
-issue.delete()
-# end project issue delete
-
-# project issue subscribe
-issue.subscribe()
-issue.unsubscribe()
-# end project issue subscribe
-
-# project issue move
-issue.move(new_project_id)
-# end project issue move
-
-# project issue todo
-issue.todo()
-# end project issue todo
-
-# project issue time tracking stats
-issue.time_stats()
-# end project issue time tracking stats
-
-# project issue set time estimate
-issue.time_estimate('3h30m')
-# end project issue set time estimate
-
-# project issue reset time estimate
-issue.reset_time_estimate()
-# end project issue reset time estimate
-
-# project issue set time spent
-issue.add_spent_time('3h30m')
-# end project issue set time spent
-
-# project issue reset time spent
-issue.reset_spent_time()
-# end project issue reset time spent
-
-# project issue useragent
-detail = issue.user_agent_detail()
-# end project issue useragent
diff --git a/docs/gl_objects/issues.rst b/docs/gl_objects/issues.rst
index 136d8b8..2f58dd6 100644
--- a/docs/gl_objects/issues.rst
+++ b/docs/gl_objects/issues.rst
@@ -14,29 +14,21 @@ Reference
   + :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
 --------
 
-List the issues:
+List the issues::
 
-.. literalinclude:: issues.py
-   :start-after: # list
-   :end-before: # end list
+    issues = gl.issues.list()
 
 Use the ``state`` and ``label`` parameters to filter the results. Use the
-``order_by`` and ``sort`` attributes to sort the results:
+``order_by`` and ``sort`` attributes to sort the results::
 
-.. literalinclude:: issues.py
-   :start-after: # filtered list
-   :end-before: # end filtered list
+    open_issues = gl.issues.list(state='opened')
+    closed_issues = gl.issues.list(state='closed')
+    tagged_issues = gl.issues.list(labels=['foo', 'bar'])
 
 Group issues
 ============
@@ -50,23 +42,18 @@ Reference
   + :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
 --------
 
-List the group issues:
+List the group issues::
 
-.. literalinclude:: issues.py
-   :start-after: # group issues list
-   :end-before: # end group issues list
+    issues = group.issues.list()
+    # Filter using the state, labels and milestone parameters
+    issues = group.issues.list(milestone='1.0', state='opened')
+    # Order using the order_by and sort parameters
+    issues = group.issues.list(order_by='created_at', sort='desc')
 
 Project issues
 ==============
@@ -80,110 +67,81 @@ Reference
   + :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
 --------
 
-List the project issues:
-
-.. literalinclude:: issues.py
-   :start-after: # project issues list
-   :end-before: # end project issues list
-
-Get a project issue:
+List the project issues::
 
-.. literalinclude:: issues.py
-   :start-after: # project issues get
-   :end-before: # end project issues get
+    issues = project.issues.list()
+    # Filter using the state, labels and milestone parameters
+    issues = project.issues.list(milestone='1.0', state='opened')
+    # Order using the order_by and sort parameters
+    issues = project.issues.list(order_by='created_at', sort='desc')
 
-Get a project issue from its `iid` (v3 only. Issues are retrieved by iid in V4 by default):
+Get a project issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issues get from iid
-   :end-before: # end project issues get from iid
+    issue = project.issues.get(issue_iid)
 
-Create a new issue:
+Create a new issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issues create
-   :end-before: # end project issues create
+    issue = project.issues.create({'title': 'I have a bug',
+                                   'description': 'Something useful here.'})
 
-Update an issue:
+Update an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue update
-   :end-before: # end project issue update
+    issue.labels = ['foo', 'bar']
+    issue.save()
 
-Close / reopen an issue:
+Close / reopen an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue open_close
-   :end-before: # end project issue open_close
+    # close an issue
+    issue.state_event = 'close'
+    issue.save()
+    # reopen it
+    issue.state_event = 'reopen'
+    issue.save()
 
-Delete an issue:
+Delete an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue delete
-   :end-before: # end project issue delete
+    project.issues.delete(issue_id)
+    # pr
+    issue.delete()
 
-Subscribe / unsubscribe from an issue:
+Subscribe / unsubscribe from an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue subscribe
-   :end-before: # end project issue subscribe
+    issue.subscribe()
+    issue.unsubscribe()
 
-Move an issue to another project:
+Move an issue to another project::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue move
-   :end-before: # end project issue move
+    issue.move(other_project_id)
 
-Make an issue as todo:
+Make an issue as todo::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue todo
-   :end-before: # end project issue todo
+    issue.todo()
 
-Get time tracking stats:
+Get time tracking stats::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue time tracking stats
-   :end-before: # end project issue time tracking stats
+    issue.time_stats()
 
-Set a time estimate for an issue:
+Set a time estimate for an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue set time estimate
-   :end-before: # end project issue set time estimate
+    issue.time_estimate('3h30m')
 
-Reset a time estimate for an issue:
+Reset a time estimate for an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue reset time estimate
-   :end-before: # end project issue reset time estimate
+    issue.reset_time_estimate()
 
-Add spent time for an issue:
+Add spent time for an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue set time spent
-   :end-before: # end project issue set time spent
+    issue.add_spent_time('3h30m')
 
-Reset spent time for an issue:
+Reset spent time for an issue::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue reset time spent
-   :end-before: # end project issue reset time spent
+    issue.reset_spent_time()
 
-Get user agent detail for the issue (admin only):
+Get user agent detail for the issue (admin only)::
 
-.. literalinclude:: issues.py
-   :start-after: # project issue useragent
-   :end-before: # end project issue useragent
+    detail = issue.user_agent_detail()
diff --git a/docs/gl_objects/labels.py b/docs/gl_objects/labels.py
deleted file mode 100644
index a63e295..0000000
--- a/docs/gl_objects/labels.py
+++ /dev/null
@@ -1,36 +0,0 @@
-# list
-labels = project.labels.list()
-# end list
-
-# get
-label = project.labels.get(label_name)
-# end get
-
-# create
-label = project.labels.create({'name': 'foo', 'color': '#8899aa'})
-# end create
-
-# update
-# change the name of the label:
-label.new_name = 'bar'
-label.save()
-# change its color:
-label.color = '#112233'
-label.save()
-# end update
-
-# delete
-project.labels.delete(label_id)
-# or
-label.delete()
-# end delete
-
-# use
-# Labels are defined as lists in issues and merge requests. The labels must
-# exist.
-issue = p.issues.create({'title': 'issue title',
-                         'description': 'issue description',
-                         'labels': ['foo']})
-issue.labels.append('bar')
-issue.save()
-# end use
diff --git a/docs/gl_objects/labels.rst b/docs/gl_objects/labels.rst
index 3c8034d..1c98971 100644
--- a/docs/gl_objects/labels.rst
+++ b/docs/gl_objects/labels.rst
@@ -11,50 +11,40 @@ Reference
   + :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
 --------
 
-List labels for a project:
-
-.. literalinclude:: labels.py
-   :start-after: # list
-   :end-before: # end list
-
-Get a single label:
+List labels for a project::
 
-.. literalinclude:: labels.py
-   :start-after: # get
-   :end-before: # end get
+    labels = project.labels.list()
 
-Create a label for a project:
+Create a label for a project::
 
-.. literalinclude:: labels.py
-   :start-after: # create
-   :end-before: # end create
+    label = project.labels.create({'name': 'foo', 'color': '#8899aa'})
 
-Update a label for a project:
+Update a label for a project::
 
-.. literalinclude:: labels.py
-   :start-after: # update
-   :end-before: # end update
+    # change the name of the label:
+    label.new_name = 'bar'
+    label.save()
+    # change its color:
+    label.color = '#112233'
+    label.save()
 
-Delete a label for a project:
+Delete a label for a project::
 
-.. literalinclude:: labels.py
-   :start-after: # delete
-   :end-before: # end delete
+    project.labels.delete(label_id)
+    # or
+    label.delete()
 
-Managing labels in issues and merge requests:
+Manage labels in issues and merge requests::
 
-.. literalinclude:: labels.py
-   :start-after: # use
-   :end-before: # end use
+    # Labels are defined as lists in issues and merge requests. The labels must
+    # exist.
+    issue = p.issues.create({'title': 'issue title',
+                             'description': 'issue description',
+                             'labels': ['foo']})
+    issue.labels.append('bar')
+    issue.save()
diff --git a/docs/gl_objects/messages.py b/docs/gl_objects/messages.py
deleted file mode 100644
index 74714e5..0000000
--- a/docs/gl_objects/messages.py
+++ /dev/null
@@ -1,23 +0,0 @@
-# list
-msgs = gl.broadcastmessages.list()
-# end list
-
-# get
-msg = gl.broadcastmessages.get(msg_id)
-# end get
-
-# create
-msg = gl.broadcastmessages.create({'message': 'Important information'})
-# end create
-
-# update
-msg.font = '#444444'
-msg.color = '#999999'
-msg.save()
-# end update
-
-# delete
-gl.broadcastmessages.delete(msg_id)
-# or
-msg.delete()
-# end delete
diff --git a/docs/gl_objects/messages.rst b/docs/gl_objects/messages.rst
index 452370d..32fbb95 100644
--- a/docs/gl_objects/messages.rst
+++ b/docs/gl_objects/messages.rst
@@ -15,46 +15,34 @@ References
   + :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
 --------
 
-List the messages:
+List the messages::
 
-.. literalinclude:: messages.py
-   :start-after: # list
-   :end-before: # end list
+    msgs = gl.broadcastmessages.list()
 
-Get a single message:
+Get a single message::
 
-.. literalinclude:: messages.py
-   :start-after: # get
-   :end-before: # end get
+    msg = gl.broadcastmessages.get(msg_id)
 
-Create a message:
+Create a message::
 
-.. literalinclude:: messages.py
-   :start-after: # create
-   :end-before: # end create
+    msg = gl.broadcastmessages.create({'message': 'Important information'})
 
-The date format for ``starts_at`` and ``ends_at`` parameters is
+The date format for the ``starts_at`` and ``ends_at`` parameters is
 ``YYYY-MM-ddThh:mm:ssZ``.
 
-Update a message:
+Update a message::
 
-.. literalinclude:: messages.py
-   :start-after: # update
-   :end-before: # end update
+    msg.font = '#444444'
+    msg.color = '#999999'
+    msg.save()
 
-Delete a message:
+Delete a message::
 
-.. literalinclude:: messages.py
-   :start-after: # delete
-   :end-before: # end delete
+    gl.broadcastmessages.delete(msg_id)
+    # or
+    msg.delete()
diff --git a/docs/gl_objects/milestones.py b/docs/gl_objects/milestones.py
deleted file mode 100644
index d1985d9..0000000
--- a/docs/gl_objects/milestones.py
+++ /dev/null
@@ -1,41 +0,0 @@
-# list
-p_milestones = project.milestones.list()
-g_milestones = group.milestones.list()
-# end list
-
-# filter
-p_milestones = project.milestones.list(state='closed')
-g_milestones = group.milestones.list(state='active')
-# end filter
-
-# get
-p_milestone = project.milestones.get(milestone_id)
-g_milestone = group.milestones.get(milestone_id)
-# end get
-
-# create
-milestone = project.milestones.create({'title': '1.0'})
-# end create
-
-# update
-milestone.description = 'v 1.0 release'
-milestone.save()
-# end update
-
-# state
-# close a milestone
-milestone.state_event = 'close'
-milestone.save()
-
-# activate a milestone
-milestone.state_event = 'activate'
-milestone.save()
-# end state
-
-# issues
-issues = milestone.issues()
-# end issues
-
-# merge_requests
-merge_requests = milestone.merge_requests()
-# end merge_requests
diff --git a/docs/gl_objects/milestones.rst b/docs/gl_objects/milestones.rst
index c96560a..0d3f576 100644
--- a/docs/gl_objects/milestones.rst
+++ b/docs/gl_objects/milestones.rst
@@ -15,13 +15,6 @@ Reference
   + :class:`gitlab.v4.objects.GroupMilestoneManager`
   + :attr:`gitlab.v4.objects.Group.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
@@ -30,11 +23,10 @@ Reference
 Examples
 --------
 
-List the milestones for a project or a group:
+List the milestones for a project or a group::
 
-.. literalinclude:: milestones.py
-   :start-after: # list
-   :end-before: # end list
+    p_milestones = project.milestones.list()
+    g_milestones = group.milestones.list()
 
 You can filter the list using the following parameters:
 
@@ -42,42 +34,39 @@ You can filter the list using the following parameters:
 * ``state``: either ``active`` or ``closed``
 * ``search``: to search using a string
 
-.. literalinclude:: milestones.py
-   :start-after: # filter
-   :end-before: # end filter
+::
+
+    p_milestones = project.milestones.list(state='closed')
+    g_milestones = group.milestones.list(state='active')
+
+Get a single milestone::
 
-Get a single milestone:
+    p_milestone = project.milestones.get(milestone_id)
+    g_milestone = group.milestones.get(milestone_id)
 
-.. literalinclude:: milestones.py
-   :start-after: # get
-   :end-before: # end get
+Create a milestone::
 
-Create a milestone:
+    milestone = project.milestones.create({'title': '1.0'})
 
-.. literalinclude:: milestones.py
-   :start-after: # create
-   :end-before: # end create
+Edit a milestone::
 
-Edit a milestone:
+    milestone.description = 'v 1.0 release'
+    milestone.save()
 
-.. literalinclude:: milestones.py
-   :start-after: # update
-   :end-before: # end update
+Change the state of a milestone (activate / close)::
 
-Change the state of a milestone (activate / close):
+    # close a milestone
+    milestone.state_event = 'close'
+    milestone.save()
 
-.. literalinclude:: milestones.py
-   :start-after: # state
-   :end-before: # end state
+    # activate a milestone
+    milestone.state_event = 'activate'
+    milestone.save()
 
-List the issues related to a milestone:
+List the issues related to a milestone::
 
-.. literalinclude:: milestones.py
-   :start-after: # issues
-   :end-before: # end issues
+    issues = milestone.issues()
 
-List the merge requests related to a milestone:
+List the merge requests related to a milestone::
 
-.. literalinclude:: milestones.py
-   :start-after: # merge_requests
-   :end-before: # end merge_requests
+    merge_requests = milestone.merge_requests()
diff --git a/docs/gl_objects/mrs.rst b/docs/gl_objects/mrs.rst
index ba1090e..731785d 100644
--- a/docs/gl_objects/mrs.rst
+++ b/docs/gl_objects/mrs.rst
@@ -5,9 +5,6 @@ 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.
 
-The v3 API uses the ``id`` attribute to identify a merge request, the v4 API
-uses the ``iid`` attribute.
-
 Reference
 ---------
 
@@ -17,13 +14,6 @@ Reference
   + :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
@@ -35,7 +25,6 @@ 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 (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``
@@ -79,8 +68,7 @@ Accept a MR::
 
 Cancel a MR when the build succeeds::
 
-    mr.cancel_merge_when_build_succeeds()  # v3
-    mr.cancel_merge_when_pipeline_succeeds()  # v4
+    mr.cancel_merge_when_pipeline_succeeds()
 
 List commits of a MR::
 
diff --git a/docs/gl_objects/namespaces.py b/docs/gl_objects/namespaces.py
deleted file mode 100644
index fe50697..0000000
--- a/docs/gl_objects/namespaces.py
+++ /dev/null
@@ -1,7 +0,0 @@
-# list
-namespaces = gl.namespaces.list()
-# end list
-
-# search
-namespaces = gl.namespaces.list(search='foo')
-# end search
diff --git a/docs/gl_objects/namespaces.rst b/docs/gl_objects/namespaces.rst
index 0dabdd9..1aebd29 100644
--- a/docs/gl_objects/namespaces.rst
+++ b/docs/gl_objects/namespaces.rst
@@ -11,25 +11,15 @@ Reference
   + :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:
+List namespaces::
 
-.. literalinclude:: namespaces.py
-   :start-after: # list
-   :end-before: # end list
+    namespaces = gl.namespaces.list()
 
-Search namespaces:
+Search namespaces::
 
-.. literalinclude:: namespaces.py
-   :start-after: # search
-   :end-before: # end search
+    namespaces = gl.namespaces.list(search='foo')
diff --git a/docs/gl_objects/notes.rst b/docs/gl_objects/notes.rst
index fd0788b..053c0a0 100644
--- a/docs/gl_objects/notes.rst
+++ b/docs/gl_objects/notes.rst
@@ -30,32 +30,6 @@ Reference
   + :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/notes.html
 
 Examples
diff --git a/docs/gl_objects/notifications.py b/docs/gl_objects/notifications.py
deleted file mode 100644
index c46e36e..0000000
--- a/docs/gl_objects/notifications.py
+++ /dev/null
@@ -1,21 +0,0 @@
-# get
-# global settings
-settings = gl.notificationsettings.get()
-# for a group
-settings = gl.groups.get(group_id).notificationsettings.get()
-# for a project
-settings = gl.projects.get(project_id).notificationsettings.get()
-# end get
-
-# update
-# use a predefined level
-settings.level = gitlab.NOTIFICATION_LEVEL_WATCH
-# create a custom setup
-settings.level = gitlab.NOTIFICATION_LEVEL_CUSTOM
-settings.save()  # will create additional attributes, but not mandatory
-
-settings.new_merge_request = True
-settings.new_issue = True
-settings.new_note = True
-settings.save()
-# end update
diff --git a/docs/gl_objects/notifications.rst b/docs/gl_objects/notifications.rst
index a7310f3..ab0287f 100644
--- a/docs/gl_objects/notifications.rst
+++ b/docs/gl_objects/notifications.rst
@@ -30,31 +30,30 @@ Reference
   + :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
 --------
 
-Get the settings:
+Get the notifications settings::
+
+    # global settings
+    settings = gl.notificationsettings.get()
+    # for a group
+    settings = gl.groups.get(group_id).notificationsettings.get()
+    # for a project
+    settings = gl.projects.get(project_id).notificationsettings.get()
+
+Update the notifications settings::
 
-.. literalinclude:: notifications.py
-   :start-after: # get
-   :end-before: # end get
+    # use a predefined level
+    settings.level = gitlab.NOTIFICATION_LEVEL_WATCH
 
-Update the settings:
+    # create a custom setup
+    settings.level = gitlab.NOTIFICATION_LEVEL_CUSTOM
+    settings.save()  # will create additional attributes, but not mandatory
 
-.. literalinclude:: notifications.py
-   :start-after: # update
-   :end-before: # end update
+    settings.new_merge_request = True
+    settings.new_issue = True
+    settings.new_note = True
+    settings.save()
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
deleted file mode 100644
index a82665a..0000000
--- a/docs/gl_objects/projects.py
+++ /dev/null
@@ -1,367 +0,0 @@
-# list
-# Active projects
-projects = gl.projects.list()
-# Archived projects
-projects = gl.projects.list(archived=1)
-# Limit to projects with a defined visibility
-projects = gl.projects.list(visibility='public')
-
-# List owned projects
-projects = gl.projects.owned()
-
-# List starred projects
-projects = gl.projects.starred()
-
-# List all the projects
-projects = gl.projects.all()
-
-# Search projects
-projects = gl.projects.list(search='keyword')
-# end list
-
-# get
-# Get a project by ID
-project = gl.projects.get(10)
-# Get a project by userspace/name
-project = gl.projects.get('myteam/myproject')
-# end get
-
-# create
-project = gl.projects.create({'name': 'project1'})
-# end create
-
-# user create
-alice = gl.users.list(username='alice')[0]
-user_project = alice.projects.create({'name': 'project'})
-user_projects = alice.projects.list()
-# end user create
-
-# update
-project.snippets_enabled = 1
-project.save()
-# end update
-
-# delete
-gl.projects.delete(1)
-# or
-project.delete()
-# end delete
-
-# fork
-fork = project.forks.create({})
-
-# fork to a specific namespace
-fork = project.forks.create({'namespace': 'myteam'})
-# end fork
-
-# forkrelation
-project.create_fork_relation(source_project.id)
-project.delete_fork_relation()
-# end forkrelation
-
-# star
-project.star()
-project.unstar()
-# end star
-
-# archive
-project.archive()
-project.unarchive()
-# end archive
-
-# members list
-members = project.members.list()
-# end members list
-
-# members search
-members = project.members.list(query='bar')
-# end members search
-
-# members get
-member = project.members.get(1)
-# end members get
-
-# members add
-member = project.members.create({'user_id': user.id, 'access_level':
-                                 gitlab.DEVELOPER_ACCESS})
-# end members add
-
-# members update
-member.access_level = gitlab.MASTER_ACCESS
-member.save()
-# end members update
-
-# members delete
-project.members.delete(user.id)
-# or
-member.delete()
-# end members delete
-
-# share
-project.share(group.id, gitlab.DEVELOPER_ACCESS)
-# end share
-
-# unshare
-project.unshare(group.id)
-# end unshare
-
-# hook list
-hooks = project.hooks.list()
-# end hook list
-
-# hook get
-hook = project.hooks.get(1)
-# end hook get
-
-# hook create
-hook = gl.project_hooks.create({'url': 'http://my/action/url',
-                                'push_events': 1},
-                               project_id=1)
-# or
-hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1})
-# end hook create
-
-# hook update
-hook.push_events = 0
-hook.save()
-# end hook update
-
-# hook delete
-project.hooks.delete(1)
-# or
-hook.delete()
-# end hook delete
-
-# repository tree
-# list the content of the root directory for the default branch
-items = project.repository_tree()
-
-# list the content of a subdirectory on a specific branch
-items = project.repository_tree(path='docs', ref='branch1')
-# end repository tree
-
-# repository blob
-items = project.repository_tree(path='docs', ref='branch1')
-file_info = p.repository_blob(items[0]['id'])
-content = base64.b64decode(file_info['content'])
-size = file_info['size']
-# end repository blob
-
-# repository raw_blob
-# find the id for the blob (simple search)
-id = [d['id'] for d in p.repository_tree() if d['name'] == 'README.rst'][0]
-
-# get the content
-file_content = p.repository_raw_blob(id)
-# end repository raw_blob
-
-# repository compare
-result = project.repository_compare('master', 'branch1')
-
-# get the commits
-for commit in result['commits']:
-    print(commit)
-
-# get the diffs
-for file_diff in result['diffs']:
-    print(file_diff)
-# end repository compare
-
-# repository archive
-# get the archive for the default branch
-tgz = project.repository_archive()
-
-# get the archive for a branch/tag/commit
-tgz = project.repository_archive(sha='4567abc')
-# end repository archive
-
-# repository contributors
-contributors = project.repository_contributors()
-# end repository contributors
-
-# housekeeping
-project.housekeeping()
-# end housekeeping
-
-# files get
-f = project.files.get(file_path='README.rst', ref='master')
-
-# get the base64 encoded content
-print(f.content)
-
-# get the decoded content
-print(f.decode())
-# end files get
-
-# files create
-# v4
-f = project.files.create({'file_path': 'testfile.txt',
-                          'branch': 'master',
-                          'content': file_content,
-                          'author_email': 'test@example.com',
-                          'author_name': 'yourname',
-                          'encoding': 'text',
-                          'commit_message': 'Create testfile'})
-# v3
-f = project.files.create({'file_path': 'testfile',
-                          'branch_name': 'master',
-                          'content': file_content,
-                          'commit_message': 'Create testfile'})
-# end files create
-
-# files update
-f.content = 'new content'
-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='master', commit_message='Update testfile', encoding='base64')
-# end files update
-
-# files delete
-f.delete(commit_message='Delete testfile')
-# end files delete
-
-# tags list
-tags = project.tags.list()
-# end tags list
-
-# tags get
-tag = project.tags.get('1.0')
-# end tags get
-
-# tags create
-tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'})
-# end tags create
-
-# tags delete
-project.tags.delete('1.0')
-# or
-tag.delete()
-# end tags delete
-
-# tags release
-tag.set_release_description('awesome v1.0 release')
-# end tags release
-
-# snippets list
-snippets = project.snippets.list()
-# end snippets list
-
-# snippets get
-snippets = project.snippets.list(snippet_id)
-# end snippets get
-
-# snippets create
-snippet = project.snippets.create({'title': 'sample 1',
-                                   'file_name': 'foo.py',
-                                   'code': 'import gitlab',
-                                   'visibility_level':
-                                   gitlab.VISIBILITY_PRIVATE})
-# end snippets create
-
-# snippets content
-print(snippet.content())
-# end snippets content
-
-# snippets update
-snippet.code = 'import gitlab\nimport whatever'
-snippet.save
-# end snippets update
-
-# snippets delete
-project.snippets.delete(snippet_id)
-# or
-snippet.delete()
-# end snippets delete
-
-# service get
-# For v3
-service = project.services.get(service_name='asana', project_id=1)
-# For v4
-service = project.services.get('asana')
-# display its status (enabled/disabled)
-print(service.active)
-# end service get
-
-# service list
-services = gl.project_services.available()  # API v3
-services = project.services.available()  # API v4
-# end service list
-
-# service update
-service.api_key = 'randomkey'
-service.save()
-# end service update
-
-# service delete
-service.delete()
-# end service delete
-
-# boards list
-boards = project.boards.list()
-# end boards list
-
-# boards get
-board = project.boards.get(board_id)
-# end boards get
-
-# board lists list
-b_lists = board.lists.list()
-# end board lists list
-
-# board lists get
-b_list = board.lists.get(list_id)
-# end board lists get
-
-# board lists create
-# First get a ProjectLabel
-label = get_or_create_label()
-# Then use its ID to create the new board list
-b_list = board.lists.create({'label_id': label.id})
-# end board lists create
-
-# board lists update
-b_list.position = 2
-b_list.save()
-# end board lists update
-
-# board lists delete
-b_list.delete()
-# end board lists delete
-
-# project file upload by path
-# Or provide a full path to the uploaded file
-project.upload("filename.txt", filepath="/some/path/filename.txt")
-# end project file upload by path
-
-# project file upload with data
-# Upload a file using its filename and filedata
-project.upload("filename.txt", filedata="Raw data")
-# end project file upload with data
-
-# project file upload markdown
-uploaded_file = project.upload("filename.txt", filedata="data")
-issue = project.issues.get(issue_id)
-issue.notes.create({
-    "body": "See the attached file: {}".format(uploaded_file["markdown"])
-})
-# end project file upload markdown
-
-# project file upload markdown custom
-uploaded_file = project.upload("filename.txt", filedata="data")
-issue = project.issues.get(issue_id)
-issue.notes.create({
-    "body": "See the [attached file]({})".format(uploaded_file["url"])
-})
-# end project file upload markdown custom
-
-# users list
-users = p.users.list()
-
-# search for users
-users = p.users.list(search='pattern')
-# end users list
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index 907f8df..fdea7aa 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -14,18 +14,14 @@ Reference
   + :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:
+List projects::
+
+    projects = gl.projects.list()
 
 The API provides several filtering parameters for the listing methods:
 
@@ -41,136 +37,148 @@ Results can also be sorted using the following parameters:
   The default is to sort by ``created_at``
 * ``sort``: sort order (``asc`` or ``desc``)
 
-.. literalinclude:: projects.py
-   :start-after: # list
-   :end-before: # end list
+::
+
+    # Archived projects
+    projects = gl.projects.list(archived=1)
+    # Limit to projects with a defined visibility
+    projects = gl.projects.list(visibility='public')
 
-Get a single project:
+    # List owned projects
+    projects = gl.projects.owned()
 
-.. literalinclude:: projects.py
-   :start-after: # get
-   :end-before: # end get
+    # List starred projects
+    projects = gl.projects.starred()
 
-Create a project:
+    # List all the projects
+    projects = gl.projects.all()
 
-.. literalinclude:: projects.py
-   :start-after: # create
-   :end-before: # end create
+    # Search projects
+    projects = gl.projects.list(search='keyword')
 
-Create a project for a user (admin only):
+Get a single project::
 
-.. literalinclude:: projects.py
-   :start-after: # user create
-   :end-before: # end user create
+    # Get a project by ID
+    project = gl.projects.get(10)
+    # Get a project by userspace/name
+    project = gl.projects.get('myteam/myproject')
 
-Create a project in a group:
+Create a project::
 
-You need to get the id of the group, then use the namespace_id attribute to create the group:
+    project = gl.projects.create({'name': 'project1'})
 
-.. code:: python
+Create a project for a user (admin only)::
 
-  group_id = gl.groups.search('my-group')[0].id
-  project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id})
+    alice = gl.users.list(username='alice')[0]
+    user_project = alice.projects.create({'name': 'project'})
+    user_projects = alice.projects.list()
 
+Create a project in a group::
 
-Update a project:
+    # You need to get the id of the group, then use the namespace_id attribute
+    # to create the group
+    group_id = gl.groups.search('my-group')[0].id
+    project = gl.projects.create({'name': 'myrepo', 'namespace_id': group_id})
 
-.. literalinclude:: projects.py
-   :start-after: # update
-   :end-before: # end update
+Update a project::
 
-Delete a project:
+    project.snippets_enabled = 1
+    project.save()
 
-.. literalinclude:: projects.py
-   :start-after: # delete
-   :end-before: # end delete
+Delete a project::
 
-Fork a project:
+    gl.projects.delete(1)
+    # or
+    project.delete()
+
+Fork a project::
+
+    fork = project.forks.create({})
 
-.. literalinclude:: projects.py
-   :start-after: # fork
-   :end-before: # end fork
+    # fork to a specific namespace
+    fork = project.forks.create({'namespace': 'myteam'})
 
-Create/delete a fork relation between projects (requires admin permissions):
+Create/delete a fork relation between projects (requires admin permissions)::
 
-.. literalinclude:: projects.py
-   :start-after: # forkrelation
-   :end-before: # end forkrelation
+    project.create_fork_relation(source_project.id)
+    project.delete_fork_relation()
 
-Star/unstar a project:
+Star/unstar a project::
 
-.. literalinclude:: projects.py
-   :start-after: # star
-   :end-before: # end star
+    project.star()
+    project.unstar()
 
-Archive/unarchive a project:
+Archive/unarchive a project::
 
-.. literalinclude:: projects.py
-   :start-after: # archive
-   :end-before: # end archive
+    project.archive()
+    project.unarchive()
 
-.. note::
+Start the housekeeping job::
 
-   Previous versions used ``archive_`` and ``unarchive_`` due to a naming issue,
-   they have been deprecated but not yet removed.
+    project.housekeeping()
 
-Start the housekeeping job:
+List the repository tree::
 
-.. literalinclude:: projects.py
-   :start-after: # housekeeping
-   :end-before: # end housekeeping
+    # list the content of the root directory for the default branch
+    items = project.repository_tree()
 
-List the repository tree:
+    # list the content of a subdirectory on a specific branch
+    items = project.repository_tree(path='docs', ref='branch1')
 
-.. literalinclude:: projects.py
-   :start-after: # repository tree
-   :end-before: # end repository tree
+Get the content and metadata of a file for a commit, using a blob sha::
 
-Get the content and metadata of a file for a commit, using a blob sha:
+    items = project.repository_tree(path='docs', ref='branch1')
+    file_info = p.repository_blob(items[0]['id'])
+    content = base64.b64decode(file_info['content'])
+    size = file_info['size']
 
-.. literalinclude:: projects.py
-   :start-after: # repository blob
-   :end-before: # end repository blob
+Get the repository archive::
 
-Get the repository archive:
+    tgz = project.repository_archive()
 
-.. literalinclude:: projects.py
-   :start-after: # repository archive
-   :end-before: # end repository archive
+    # get the archive for a branch/tag/commit
+    tgz = project.repository_archive(sha='4567abc')
 
 .. warning::
 
    Archives are entirely stored in memory unless you use the streaming feature.
    See :ref:`the artifacts example <streaming_example>`.
 
-Get the content of a file using the blob id:
+Get the content of a file using the blob id::
 
-.. literalinclude:: projects.py
-   :start-after: # repository raw_blob
-   :end-before: # end repository raw_blob
+    # find the id for the blob (simple search)
+    id = [d['id'] for d in p.repository_tree() if d['name'] == 'README.rst'][0]
+
+    # get the content
+    file_content = p.repository_raw_blob(id)
 
 .. warning::
 
    Blobs are entirely stored in memory unless you use the streaming feature.
    See :ref:`the artifacts example <streaming_example>`.
 
-Compare two branches, tags or commits:
+Compare two branches, tags or commits::
+
+    result = project.repository_compare('master', 'branch1')
 
-.. literalinclude:: projects.py
-   :start-after: # repository compare
-   :end-before: # end repository compare
+    # get the commits
+    for commit in result['commits']:
+        print(commit)
 
-Get a list of contributors for the repository:
+    # get the diffs
+    for file_diff in result['diffs']:
+        print(file_diff)
 
-.. literalinclude:: projects.py
-   :start-after: # repository contributors
-   :end-before: # end repository contributors
+Get a list of contributors for the repository::
 
-Get a list of users for the repository:
+    contributors = project.repository_contributors()
 
-.. literalinclude:: projects.py
-   :start-after: # users list
-   :end-before: # end users list
+Get a list of users for the repository::
+
+    users = p.users.list()
+
+    # search for users
+    users = p.users.list(search='pattern')
 
 Project custom attributes
 =========================
@@ -224,42 +232,46 @@ Reference
   + :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:
+Get a file::
+
+    f = project.files.get(file_path='README.rst', ref='master')
 
-.. literalinclude:: projects.py
-   :start-after: # files get
-   :end-before: # end files get
+    # get the base64 encoded content
+    print(f.content)
 
-Create a new file:
+    # get the decoded content
+    print(f.decode())
 
-.. literalinclude:: projects.py
-   :start-after: # files create
-   :end-before: # end files create
+Create a new file::
+
+    f = project.files.create({'file_path': 'testfile.txt',
+                              'branch': 'master',
+                              'content': file_content,
+                              'author_email': 'test@example.com',
+                              'author_name': 'yourname',
+                              'encoding': 'text',
+                              'commit_message': 'Create testfile'})
 
 Update a file. The entire content must be uploaded, as plain text or as base64
-encoded text:
+encoded text::
+
+    f.content = 'new content'
+    f.save(branch='master', commit_message='Update testfile') 
 
-.. literalinclude:: projects.py
-   :start-after: # files update
-   :end-before: # end files update
+    # 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='master', commit_message='Update testfile', encoding='base64')
 
-Delete a file:
+Delete a file::
 
-.. literalinclude:: projects.py
-   :start-after: # files delete
-   :end-before: # end files delete
+    f.delete(commit_message='Delete testfile')
 
 Project tags
 ============
@@ -273,47 +285,32 @@ Reference
   + :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`
-
 * GitLab API: https://docs.gitlab.com/ce/api/tags.html
 
 Examples
 --------
 
-List the project tags:
+List the project tags::
 
-.. literalinclude:: projects.py
-   :start-after: # tags list
-   :end-before: # end tags list
+    tags = project.tags.list()
 
-Get a tag:
+Get a tag::
 
-.. literalinclude:: projects.py
-   :start-after: # tags get
-   :end-before: # end tags get
+    tag = project.tags.get('1.0')
 
-Create a tag:
+Create a tag::
 
-.. literalinclude:: projects.py
-   :start-after: # tags create
-   :end-before: # end tags create
+    tag = project.tags.create({'tag_name': '1.0', 'ref': 'master'})
 
-Set or update the release note for a tag:
+Set or update the release note for a tag::
 
-.. literalinclude:: projects.py
-   :start-after: # tags release
-   :end-before: # end tags release
+    tag.set_release_description('awesome v1.0 release')
 
-Delete a tag:
+Delete a tag::
 
-.. literalinclude:: projects.py
-   :start-after: # tags delete
-   :end-before: # end tags delete
+    project.tags.delete('1.0')
+    # or
+    tag.delete()
 
 .. _project_snippets:
 
@@ -335,58 +332,46 @@ Reference
   + :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:
+List the project snippets::
 
-.. literalinclude:: projects.py
-   :start-after: # snippets list
-   :end-before: # end snippets list
+    snippets = project.snippets.list()
 
-Get a snippet:
+Get a snippet::
 
-.. literalinclude:: projects.py
-   :start-after: # snippets get
-   :end-before: # end snippets get
+    snippets = project.snippets.list(snippet_id)
 
-Get the content of a snippet:
+Get the content of a snippet::
 
-.. literalinclude:: projects.py
-   :start-after: # snippets content
-   :end-before: # end snippets content
+    print(snippet.content())
 
 .. warning::
 
    The snippet content is entirely stored in memory unless you use the
    streaming feature. See :ref:`the artifacts example <streaming_example>`.
 
-Create a snippet:
+Create a snippet::
 
-.. literalinclude:: projects.py
-   :start-after: # snippets create
-   :end-before: # end snippets create
+    snippet = project.snippets.create({'title': 'sample 1',
+                                       'file_name': 'foo.py',
+                                       'code': 'import gitlab',
+                                       'visibility_level':
+                                       gitlab.VISIBILITY_PRIVATE})
 
-Update a snippet:
+Update a snippet::
 
-.. literalinclude:: projects.py
-   :start-after: # snippets update
-   :end-before: # end snippets update
+    snippet.code = 'import gitlab\nimport whatever'
+    snippet.save
 
-Delete a snippet:
+Delete a snippet::
 
-.. literalinclude:: projects.py
-   :start-after: # snippets delete
-   :end-before: # end snippets delete
+    project.snippets.delete(snippet_id)
+    # or
+    snippet.delete()
 
 Notes
 =====
@@ -405,59 +390,43 @@ Reference
   + :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:
+List the project members::
 
-.. literalinclude:: projects.py
-   :start-after: # members list
-   :end-before: # end members list
+    members = project.members.list()
 
-Search project members matching a query string:
+Search project members matching a query string::
 
-.. literalinclude:: projects.py
-   :start-after: # members search
-   :end-before: # end members search
+    members = project.members.list(query='bar')
 
-Get a single project member:
+Get a single project member::
 
-.. literalinclude:: projects.py
-   :start-after: # members get
-   :end-before: # end members get
+    member = project.members.get(1)
 
-Add a project member:
+Add a project member::
 
-.. literalinclude:: projects.py
-   :start-after: # members add
-   :end-before: # end members add
+    member = project.members.create({'user_id': user.id, 'access_level':
+                                     gitlab.DEVELOPER_ACCESS})
 
-Modify a project member (change the access level):
+Modify a project member (change the access level)::
 
-.. literalinclude:: projects.py
-   :start-after: # members update
-   :end-before: # end members update
+    member.access_level = gitlab.MASTER_ACCESS
+    member.save()
 
-Remove a member from the project team:
+Remove a member from the project team::
 
-.. literalinclude:: projects.py
-   :start-after: # members delete
-   :end-before: # end members delete
+    project.members.delete(user.id)
+    # or
+    member.delete()
 
-Share the project with a group:
+Share/unshare the project with a group::
 
-.. literalinclude:: projects.py
-   :start-after: # share
-   :end-before: # end share
+    project.share(group.id, gitlab.DEVELOPER_ACCESS)
+    project.unshare(group.id)
 
 Project hooks
 =============
@@ -471,47 +440,33 @@ Reference
   + :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
 
 Examples
 --------
 
-List the project hooks:
+List the project hooks::
 
-.. literalinclude:: projects.py
-   :start-after: # hook list
-   :end-before: # end hook list
+    hooks = project.hooks.list()
 
-Get a project hook:
+Get a project hook::
 
-.. literalinclude:: projects.py
-   :start-after: # hook get
-   :end-before: # end hook get
+    hook = project.hooks.get(1)
 
-Create a project hook:
+Create a project hook::
 
-.. literalinclude:: projects.py
-   :start-after: # hook create
-   :end-before: # end hook create
+    hook = project.hooks.create({'url': 'http://my/action/url', 'push_events': 1})
 
-Update a project hook:
+Update a project hook::
 
-.. literalinclude:: projects.py
-   :start-after: # hook update
-   :end-before: # end hook update
+    hook.push_events = 0
+    hook.save()
 
-Delete a project hook:
+Delete a project hook::
 
-.. literalinclude:: projects.py
-   :start-after: # hook delete
-   :end-before: # end hook delete
+    project.hooks.delete(1)
+    # or
+    hook.delete()
 
 Project Services
 ================
@@ -525,41 +480,29 @@ Reference
   + :class:`gitlab.v4.objects.ProjectServiceManager`
   + :attr:`gitlab.v4.objects.Project.services`
 
-* v3 API:
-
-  + :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
 
 Examples
 ---------
 
-Get a service:
+Get a service::
 
-.. literalinclude:: projects.py
-   :start-after: # service get
-   :end-before: # end service get
+    service = project.services.get('asana')
+    # display its status (enabled/disabled)
+    print(service.active)
 
-List the code names of available services (doesn't return objects):
+List the code names of available services (doesn't return objects)::
 
-.. literalinclude:: projects.py
-   :start-after: # service list
-   :end-before: # end service list
+    services = project.services.available()
 
-Configure and enable a service:
+Configure and enable a service::
 
-.. literalinclude:: projects.py
-   :start-after: # service update
-   :end-before: # end service update
+    service.api_key = 'randomkey'
+    service.save()
 
-Disable a service:
+Disable a service::
 
-.. literalinclude:: projects.py
-   :start-after: # service delete
-   :end-before: # end service delete
+    service.delete()
 
 Issue boards
 ============
@@ -577,29 +520,18 @@ Reference
   + :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:
+Get the list of existing boards for a project::
 
-.. literalinclude:: projects.py
-   :start-after: # boards list
-   :end-before: # end boards list
+    boards = project.boards.list()
 
-Get a single board for a project:
+Get a single board for a project::
 
-.. literalinclude:: projects.py
-   :start-after: # boards get
-   :end-before: # end boards get
+    board = project.boards.get(board_id)
 
 Board lists
 ===========
@@ -613,49 +545,35 @@ Reference
   + :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:
+List the issue lists for a board::
 
-.. literalinclude:: projects.py
-   :start-after: # board lists list
-   :end-before: # end board lists list
+    b_lists = board.lists.list()
 
-Get a single list:
+Get a single list::
 
-.. literalinclude:: projects.py
-   :start-after: # board lists get
-   :end-before: # end board lists get
+    b_list = board.lists.get(list_id)
 
-Create a new list:
+Create a new list::
 
-.. literalinclude:: projects.py
-   :start-after: # board lists create
-   :end-before: # end board lists create
+    # First get a ProjectLabel
+    label = get_or_create_label()
+    # Then use its ID to create the new board list
+    b_list = board.lists.create({'label_id': label.id})
 
 Change a list position. The first list is at position 0. Moving a list will
-set it at the given position and move the following lists up a position:
+set it at the given position and move the following lists up a position::
 
-.. literalinclude:: projects.py
-   :start-after: # board lists update
-   :end-before: # end board lists update
+    b_list.position = 2
+    b_list.save()
 
-Delete a list:
+Delete a list::
 
-.. literalinclude:: projects.py
-   :start-after: # board lists delete
-   :end-before: # end board lists delete
+    b_list.delete()
 
 
 File uploads
@@ -668,37 +586,33 @@ Reference
 
   + :attr:`gitlab.v4.objects.Project.upload`
 
-* v3 API:
-
-  + :attr:`gitlab.v3.objects.Project.upload`
-
 * Gitlab API: https://docs.gitlab.com/ce/api/projects.html#upload-a-file
 
 Examples
 --------
 
-Upload a file into a project using a filesystem path:
+Upload a file into a project using a filesystem path::
 
-.. literalinclude:: projects.py
-   :start-after: # project file upload by path
-   :end-before: # end project file upload by path
+    project.upload("filename.txt", filepath="/some/path/filename.txt")
 
-Upload a file into a project without a filesystem path:
+Upload a file into a project without a filesystem path::
 
-.. literalinclude:: projects.py
-   :start-after: # project file upload with data
-   :end-before: # end project file upload with data
+    project.upload("filename.txt", filedata="Raw data")
 
 Upload a file and comment on an issue using the uploaded file's
-markdown:
+markdown::
 
-.. literalinclude:: projects.py
-   :start-after: # project file upload markdown
-   :end-before: # end project file upload markdown
+    uploaded_file = project.upload("filename.txt", filedata="data")
+    issue = project.issues.get(issue_id)
+    issue.notes.create({
+        "body": "See the attached file: {}".format(uploaded_file["markdown"])
+    })
 
 Upload a file and comment on an issue while using custom
-markdown to reference the uploaded file:
+markdown to reference the uploaded file::
 
-.. literalinclude:: projects.py
-   :start-after: # project file upload markdown custom
-   :end-before: # end project file upload markdown custom
+    uploaded_file = project.upload("filename.txt", filedata="data")
+    issue = project.issues.get(issue_id)
+    issue.notes.create({
+        "body": "See the [attached file]({})".format(uploaded_file["url"])
+    })
diff --git a/docs/gl_objects/protected_branches.rst b/docs/gl_objects/protected_branches.rst
index 4a6c837..006bb8b 100644
--- a/docs/gl_objects/protected_branches.rst
+++ b/docs/gl_objects/protected_branches.rst
@@ -19,26 +19,20 @@ References
 Examples
 --------
 
-Get the list of protected branches for a project:
+Get the list of protected branches for a project::
 
-.. literalinclude:: branches.py
-   :start-after: # p_branch list
-   :end-before: # end p_branch list
+    p_branches = project.protectedbranches.list()
 
-Get a single protected branch:
+Get a single protected branch::
 
-.. literalinclude:: branches.py
-   :start-after: # p_branch get
-   :end-before: # end p_branch get
+    p_branch = project.protectedbranches.get('master')
 
-Create a protected branch:
+Create a protected branch::
 
-.. literalinclude:: branches.py
-   :start-after: # p_branch create
-   :end-before: # end p_branch create
+    p_branch = project.protectedbranches.create({'name': '*-stable'})
 
-Delete a protected branch:
+Delete a protected branch::
 
-.. literalinclude:: branches.py
-   :start-after: # p_branch delete
-   :end-before: # end p_branch delete
+    project.protectedbranches.delete('*-stable')
+    # or
+    p_branch.delete()
diff --git a/docs/gl_objects/runners.py b/docs/gl_objects/runners.py
deleted file mode 100644
index 93aca0d..0000000
--- a/docs/gl_objects/runners.py
+++ /dev/null
@@ -1,36 +0,0 @@
-# list
-# List owned runners
-runners = gl.runners.list()
-# With a filter
-runners = gl.runners.list(scope='active')
-# List all runners, using a filter
-runners = gl.runners.all(scope='paused')
-# end list
-
-# get
-runner = gl.runners.get(runner_id)
-# end get
-
-# update
-runner = gl.runners.get(runner_id)
-runner.tag_list.append('new_tag')
-runner.save()
-# end update
-
-# delete
-gl.runners.delete(runner_id)
-# or
-runner.delete()
-# end delete
-
-# project list
-runners = project.runners.list()
-# end project list
-
-# project enable
-p_runner = project.runners.create({'runner_id': runner.id})
-# end project enable
-
-# project disable
-project.runners.delete(runner.id)
-# end project disable
diff --git a/docs/gl_objects/runners.rst b/docs/gl_objects/runners.rst
index e26c8af..70bd60f 100644
--- a/docs/gl_objects/runners.rst
+++ b/docs/gl_objects/runners.rst
@@ -20,12 +20,6 @@ Reference
   + :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
@@ -47,27 +41,30 @@ for this parameter are:
    The returned objects hold minimal information about the runners. Use the
    ``get()`` method to retrieve detail about a runner.
 
-.. literalinclude:: runners.py
-   :start-after: # list
-   :end-before: # end list
+::
 
-Get a runner's detail:
+    # List owned runners
+    runners = gl.runners.list()
+    # With a filter
+    runners = gl.runners.list(scope='active')
+    # List all runners, using a filter
+    runners = gl.runners.all(scope='paused')
 
-.. literalinclude:: runners.py
-   :start-after: # get
-   :end-before: # end get
+Get a runner's detail::
 
-Update a runner:
+    runner = gl.runners.get(runner_id)
 
-.. literalinclude:: runners.py
-   :start-after: # update
-   :end-before: # end update
+Update a runner::
 
-Remove a runner:
+    runner = gl.runners.get(runner_id)
+    runner.tag_list.append('new_tag')
+    runner.save()
 
-.. literalinclude:: runners.py
-   :start-after: # delete
-   :end-before: # end delete
+Remove a runner::
+
+    gl.runners.delete(runner_id)
+    # or
+    runner.delete()
 
 Project runners
 ===============
@@ -81,32 +78,19 @@ Reference
   + :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
 --------
 
-List the runners for a project:
+List the runners for a project::
 
-.. literalinclude:: runners.py
-   :start-after: # project list
-   :end-before: # end project list
+    runners = project.runners.list()
 
-Enable a specific runner for a project:
+Enable a specific runner for a project::
 
-.. literalinclude:: runners.py
-   :start-after: # project enable
-   :end-before: # end project enable
+    p_runner = project.runners.create({'runner_id': runner.id})
 
-Disable a specific runner for a project:
+Disable a specific runner for a project::
 
-.. literalinclude:: runners.py
-   :start-after: # project disable
-   :end-before: # end project disable
+    project.runners.delete(runner.id)
diff --git a/docs/gl_objects/settings.py b/docs/gl_objects/settings.py
deleted file mode 100644
index 834d43d..0000000
--- a/docs/gl_objects/settings.py
+++ /dev/null
@@ -1,8 +0,0 @@
-# get
-settings = gl.settings.get()
-# end get
-
-# update
-s.signin_enabled = False
-s.save()
-# end update
diff --git a/docs/gl_objects/settings.rst b/docs/gl_objects/settings.rst
index cf3fd4d..4accfe0 100644
--- a/docs/gl_objects/settings.rst
+++ b/docs/gl_objects/settings.rst
@@ -11,25 +11,16 @@ Reference
   + :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/settings.html
 
 Examples
 --------
 
-Get the settings:
+Get the settings::
 
-.. literalinclude:: settings.py
-   :start-after: # get
-   :end-before: # end get
+    settings = gl.settings.get()
 
-Update the settings:
+Update the settings::
 
-.. literalinclude:: settings.py
-   :start-after: # update
-   :end-before: # end update
+    settings.signin_enabled = False
+    settings.save()
diff --git a/docs/gl_objects/sidekiq.rst b/docs/gl_objects/sidekiq.rst
index 593dda0..5f44762 100644
--- a/docs/gl_objects/sidekiq.rst
+++ b/docs/gl_objects/sidekiq.rst
@@ -10,11 +10,6 @@ Reference
   + :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/snippets.py b/docs/gl_objects/snippets.py
deleted file mode 100644
index 87d1a42..0000000
--- a/docs/gl_objects/snippets.py
+++ /dev/null
@@ -1,33 +0,0 @@
-# list
-snippets = gl.snippets.list()
-# end list
-
-# public list
-public_snippets = gl.snippets.public()
-# end public list
-
-# get
-snippet = gl.snippets.get(snippet_id)
-# get the content - API v4
-content = snippet.content()
-
-# get the content - API v3
-content = snippet.raw()
-# end get
-
-# create
-snippet = gl.snippets.create({'title': 'snippet1',
-                              'file_name': 'snippet1.py',
-                              'content': open('snippet1.py').read()})
-# end create
-
-# update
-snippet.visibility_level = gitlab.Project.VISIBILITY_PUBLIC
-snippet.save()
-# end update
-
-# delete
-gl.snippets.delete(snippet_id)
-# or
-snippet.delete()
-# end delete
diff --git a/docs/gl_objects/snippets.rst b/docs/gl_objects/snippets.rst
index 34c39fb..5493db0 100644
--- a/docs/gl_objects/snippets.rst
+++ b/docs/gl_objects/snippets.rst
@@ -2,32 +2,33 @@
 Snippets
 ########
 
-You can store code snippets in Gitlab. Snippets can be attached to projects
-(see :ref:`project_snippets`), but can also be detached.
+Reference
+=========
 
-* Object class: :class:`gitlab.objects.Namespace`
-* Manager object: :attr:`gitlab.Gitlab.snippets`
+* v4 API:
+
+  + :class:`gitlab.v4.objects.Snippet`
+  + :class:`gitlab.v4.objects.SnipptManager`
+  + :attr:`gilab.Gitlab.snippets`
+
+* GitLab API: https://docs.gitlab.com/ce/api/snippets.html
 
 Examples
 ========
 
-List snippets woned by the current user:
+List snippets owned by the current user::
 
-.. literalinclude:: snippets.py
-   :start-after: # list
-   :end-before: # end list
+    snippets = gl.snippets.list()
 
-List the public snippets:
+List the public snippets::
 
-.. literalinclude:: snippets.py
-   :start-after: # public list
-   :end-before: # end public list
+    public_snippets = gl.snippets.public()
 
-Get a snippet:
+Get a snippet::
 
-.. literalinclude:: snippets.py
-   :start-after: # get
-   :end-before: # end get
+    snippet = gl.snippets.get(snippet_id)
+    # get the content
+    content = snippet.content()
 
 .. warning::
 
@@ -35,20 +36,19 @@ Get a snippet:
    See :ref:`the artifacts example <streaming_example>`.
 
 
-Create a snippet:
+Create a snippet::
 
-.. literalinclude:: snippets.py
-   :start-after: # create
-   :end-before: # end create
+    snippet = gl.snippets.create({'title': 'snippet1',
+                                  'file_name': 'snippet1.py',
+                                  'content': open('snippet1.py').read()})
 
-Update a snippet:
+Update a snippet::
 
-.. literalinclude:: snippets.py
-   :start-after: # update
-   :end-before: # end update
+    snippet.visibility_level = gitlab.Project.VISIBILITY_PUBLIC
+    snippet.save()
 
-Delete a snippet:
+Delete a snippet::
 
-.. literalinclude:: snippets.py
-   :start-after: # delete
-   :end-before: # end delete
+    gl.snippets.delete(snippet_id)
+    # or
+    snippet.delete()
diff --git a/docs/gl_objects/system_hooks.py b/docs/gl_objects/system_hooks.py
deleted file mode 100644
index 9bc487b..0000000
--- a/docs/gl_objects/system_hooks.py
+++ /dev/null
@@ -1,17 +0,0 @@
-# list
-hooks = gl.hooks.list()
-# end list
-
-# test
-gl.hooks.get(hook_id)
-# end test
-
-# create
-hook = gl.hooks.create({'url': 'http://your.target.url'})
-# end create
-
-# delete
-gl.hooks.delete(hook_id)
-# or
-hook.delete()
-# end delete
diff --git a/docs/gl_objects/system_hooks.rst b/docs/gl_objects/system_hooks.rst
index a9e9fee..6203168 100644
--- a/docs/gl_objects/system_hooks.rst
+++ b/docs/gl_objects/system_hooks.rst
@@ -11,37 +11,25 @@ Reference
   + :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
 --------
 
-List the system hooks:
+List the system hooks::
 
-.. literalinclude:: system_hooks.py
-   :start-after: # list
-   :end-before: # end list
+    hooks = gl.hooks.list()
 
-Create a system hook:
+Create a system hook::
 
-.. literalinclude:: system_hooks.py
-   :start-after: # create
-   :end-before: # end create
+    gl.hooks.get(hook_id)
 
-Test a system hook. The returned object is not usable (it misses the hook ID):
+Test a system hook. The returned object is not usable (it misses the hook ID)::
 
-.. literalinclude:: system_hooks.py
-   :start-after: # test
-   :end-before: # end test
+    hook = gl.hooks.create({'url': 'http://your.target.url'})
 
-Delete a system hook:
+Delete a system hook::
 
-.. literalinclude:: system_hooks.py
-   :start-after: # delete
-   :end-before: # end delete
+    gl.hooks.delete(hook_id)
+    # or
+    hook.delete()
diff --git a/docs/gl_objects/templates.py b/docs/gl_objects/templates.py
deleted file mode 100644
index 0874dc7..0000000
--- a/docs/gl_objects/templates.py
+++ /dev/null
@@ -1,35 +0,0 @@
-# license list
-licenses = gl.licenses.list()
-# end license list
-
-# license get
-license = gl.licenses.get('apache-2.0', project='foobar', fullname='John Doe')
-print(license.content)
-# end license get
-
-# gitignore list
-gitignores = gl.gitignores.list()
-# end gitignore list
-
-# gitignore get
-gitignore = gl.gitignores.get('Python')
-print(gitignore.content)
-# end gitignore get
-
-# gitlabciyml list
-gitlabciymls = gl.gitlabciymls.list()
-# end gitlabciyml list
-
-# gitlabciyml get
-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 c43b7ae..f939e5f 100644
--- a/docs/gl_objects/templates.rst
+++ b/docs/gl_objects/templates.rst
@@ -21,28 +21,19 @@ Reference
   + :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
 --------
 
-List known license templates:
+List known license templates::
 
-.. literalinclude:: templates.py
-   :start-after: # license list
-   :end-before: # end license list
+    licenses = gl.licenses.list()
 
-Generate a license content for a project:
+Generate a license content for a project::
 
-.. literalinclude:: templates.py
-   :start-after: # license get
-   :end-before: # end license get
+    license = gl.licenses.get('apache-2.0', project='foobar', fullname='John Doe')
+    print(license.content)
 
 .gitignore templates
 ====================
@@ -56,28 +47,19 @@ Reference
   + :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
 --------
 
-List known gitignore templates:
+List known gitignore templates::
 
-.. literalinclude:: templates.py
-   :start-after: # gitignore list
-   :end-before: # end gitignore list
+    gitignores = gl.gitignores.list()
 
-Get a gitignore template:
+Get a gitignore template::
 
-.. literalinclude:: templates.py
-   :start-after: # gitignore get
-   :end-before: # end gitignore get
+    gitignore = gl.gitignores.get('Python')
+    print(gitignore.content)
 
 GitLab CI templates
 ===================
@@ -91,28 +73,19 @@ Reference
   + :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
 --------
 
-List known GitLab CI templates:
+List known GitLab CI templates::
 
-.. literalinclude:: templates.py
-   :start-after: # gitlabciyml list
-   :end-before: # end gitlabciyml list
+    gitlabciymls = gl.gitlabciymls.list()
 
-Get a GitLab CI template:
+Get a GitLab CI template::
 
-.. literalinclude:: templates.py
-   :start-after: # gitlabciyml get
-   :end-before: # end gitlabciyml get
+    gitlabciyml = gl.gitlabciymls.get('Pelican')
+    print(gitlabciyml.content)
 
 Dockerfile templates
 ====================
@@ -131,14 +104,11 @@ Reference
 Examples
 --------
 
-List known Dockerfile templates:
+List known Dockerfile templates::
 
-.. literalinclude:: templates.py
-   :start-after: # dockerfile list
-   :end-before: # end dockerfile list
+    dockerfiles = gl.dockerfiles.list()
 
-Get a Dockerfile template:
+Get a Dockerfile template::
 
-.. literalinclude:: templates.py
-   :start-after: # dockerfile get
-   :end-before: # end dockerfile get
+    dockerfile = gl.dockerfiles.get('Python')
+    print(dockerfile.content)
diff --git a/docs/gl_objects/todos.py b/docs/gl_objects/todos.py
deleted file mode 100644
index 74ec211..0000000
--- a/docs/gl_objects/todos.py
+++ /dev/null
@@ -1,22 +0,0 @@
-# list
-todos = gl.todos.list()
-# end list
-
-# filter
-todos = gl.todos.list(project_id=1)
-todos = gl.todos.list(state='done', type='Issue')
-# end filter
-
-# get
-todo = gl.todos.get(todo_id)
-# end get
-
-# delete
-gl.todos.delete(todo_id)
-# or
-todo.delete()
-# end delete
-
-# all_delete
-nb_of_closed_todos = gl.todos.delete_all()
-# end all_delete
diff --git a/docs/gl_objects/todos.rst b/docs/gl_objects/todos.rst
index bd7f1fa..a01aa43 100644
--- a/docs/gl_objects/todos.rst
+++ b/docs/gl_objects/todos.rst
@@ -2,17 +2,23 @@
 Todos
 #####
 
-Use :class:`~gitlab.objects.Todo` objects to manipulate todos. The
-:attr:`gitlab.Gitlab.todos` manager object provides helper functions.
+Reference
+---------
+
+* v4 API:
+
+  + :class:`~gitlab.objects.Todo`
+  + :class:`~gitlab.objects.TodoManager`
+  + :attr:`gitlab.Gitlab.todos`
+
+* GitLab API: https://docs.gitlab.com/ce/api/todos.html
 
 Examples
 --------
 
-List active todos:
+List active todos::
 
-.. literalinclude:: todos.py
-   :start-after: # list
-   :end-before: # end list
+    todos = gl.todos.list()
 
 You can filter the list using the following parameters:
 
@@ -23,26 +29,17 @@ You can filter the list using the following parameters:
 * ``state``: can be ``pending`` or ``done``
 * ``type``: can be ``Issue`` or ``MergeRequest``
 
-For example:
-
-.. literalinclude:: todos.py
-   :start-after: # filter
-   :end-before: # end filter
-
-Get a single todo:
+For example::
 
-.. literalinclude:: todos.py
-   :start-after: # get
-   :end-before: # end get
+    todos = gl.todos.list(project_id=1)
+    todos = gl.todos.list(state='done', type='Issue')
 
-Mark a todo as done:
+Mark a todo as done::
 
-.. literalinclude:: todos.py
-   :start-after: # delete
-   :end-before: # end delete
+    gl.todos.delete(todo_id)
+    # or
+    todo.delete()
 
-Mark all the todos as done:
+Mark all the todos as done::
 
-.. literalinclude:: todos.py
-   :start-after: # all_delete
-   :end-before: # end all_delete
+    nb_of_closed_todos = gl.todos.delete_all()
diff --git a/docs/gl_objects/users.py b/docs/gl_objects/users.py
deleted file mode 100644
index 842e35d..0000000
--- a/docs/gl_objects/users.py
+++ /dev/null
@@ -1,118 +0,0 @@
-# list
-users = gl.users.list()
-# end list
-
-# search
-users = gl.users.list(search='oo')
-# end search
-
-# get
-# by ID
-user = gl.users.get(2)
-# by username
-user = gl.users.list(username='root')[0]
-# end get
-
-# create
-user = gl.users.create({'email': 'john@doe.com',
-                        'password': 's3cur3s3cr3T',
-                        'username': 'jdoe',
-                        'name': 'John Doe'})
-# end create
-
-# update
-user.name = 'Real Name'
-user.save()
-# end update
-
-# delete
-gl.users.delete(2)
-user.delete()
-# end delete
-
-# block
-user.block()
-user.unblock()
-# end block
-
-# key list
-keys = user.keys.list()
-# end key list
-
-# key get
-key = user.keys.get(1)
-# end key get
-
-# key create
-k = user.keys.create({'title': 'my_key',
-                      'key': open('/home/me/.ssh/id_rsa.pub').read()})
-# end key create
-
-# key delete
-user.keys.delete(1)
-# or
-key.delete()
-# end key delete
-
-# gpgkey list
-gpgkeys = user.gpgkeys.list()
-# end gpgkey list
-
-# gpgkey get
-gpgkey = user.gpgkeys.get(1)
-# end gpgkey get
-
-# gpgkey create
-# get the key with `gpg --export -a GPG_KEY_ID`
-k = user.gpgkeys.create({'key': public_key_content})
-# end gpgkey create
-
-# gpgkey delete
-user.gpgkeys.delete(1)
-# or
-gpgkey.delete()
-# end gpgkey delete
-
-# email list
-emails = user.emails.list()
-# end email list
-
-# email get
-email = gl.user_emails.list(1, user_id=1)
-# or
-email = user.emails.get(1)
-# end email get
-
-# email create
-k = user.emails.create({'email': 'foo@bar.com'})
-# end email create
-
-# email delete
-user.emails.delete(1)
-# or
-email.delete()
-# end email delete
-
-# currentuser get
-gl.auth()
-current_user = gl.user
-# end currentuser get
-
-# it list
-i_t = user.impersonationtokens.list(state='active')
-i_t = user.impersonationtokens.list(state='inactive')
-# end it list
-
-# it get
-i_t = user.impersonationtokens.get(i_t_id)
-# end it get
-
-# it create
-i_t = user.impersonationtokens.create({'name': 'token1', 'scopes': ['api']})
-# use the token to create a new gitlab connection
-user_gl = gitlab.Gitlab(gitlab_url, private_token=i_t.token)
-# end it create
-
-# it delete
-i_t.delete()
-# end it delete
diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst
index bbb96ee..a1d6dd6 100644
--- a/docs/gl_objects/users.rst
+++ b/docs/gl_objects/users.rst
@@ -19,58 +19,47 @@ References
   + :class:`gitlab.v4.objects.UserManager`
   + :attr:`gitlab.Gitlab.users`
 
-* v3 API:
-
-  + :class:`gitlab.v3.objects.User`
-  + :class:`gitlab.v3.objects.UserManager`
-  + :attr:`gitlab.Gitlab.users`
-
 * GitLab API: https://docs.gitlab.com/ce/api/users.html
 
 Examples
 --------
 
-Get the list of users:
+Get the list of users::
 
-.. literalinclude:: users.py
-   :start-after: # list
-   :end-before: # end list
+    users = gl.users.list()
 
-Search users whose username match the given string:
+Search users whose username match a given string::
 
-.. literalinclude:: users.py
-   :start-after: # search
-   :end-before: # end search
+    users = gl.users.list(search='foo')
 
-Get a single user:
+Get a single user::
 
-.. literalinclude:: users.py
-   :start-after: # get
-   :end-before: # end get
+    # by ID
+    user = gl.users.get(2)
+    # by username
+    user = gl.users.list(username='root')[0]
 
-Create a user:
+Create a user::
 
-.. literalinclude:: users.py
-   :start-after: # create
-   :end-before: # end create
+    user = gl.users.create({'email': 'john@doe.com',
+                            'password': 's3cur3s3cr3T',
+                            'username': 'jdoe',
+                            'name': 'John Doe'})
 
-Update a user:
+Update a user::
 
-.. literalinclude:: users.py
-   :start-after: # update
-   :end-before: # end update
+    user.name = 'Real Name'
+    user.save()
 
-Delete a user:
+Delete a user::
 
-.. literalinclude:: users.py
-   :start-after: # delete
-   :end-before: # end delete
+    gl.users.delete(2)
+    user.delete()
 
-Block/Unblock a user:
+Block/Unblock a user::
 
-.. literalinclude:: users.py
-   :start-after: # block
-   :end-before: # end block
+    user.block()
+    user.unblock()
 
 User custom attributes
 ======================
@@ -126,29 +115,24 @@ References
 
 * GitLab API: https://docs.gitlab.com/ce/api/users.html#get-all-impersonation-tokens-of-a-user
 
-List impersonation tokens for a user:
+List impersonation tokens for a user::
 
-.. literalinclude:: users.py
-   :start-after: # it list
-   :end-before: # end it list
+    i_t = user.impersonationtokens.list(state='active')
+    i_t = user.impersonationtokens.list(state='inactive')
 
-Get an impersonation token for a user:
+Get an impersonation token for a user::
 
-.. literalinclude:: users.py
-   :start-after: # it get
-   :end-before: # end it get
+    i_t = user.impersonationtokens.get(i_t_id)
 
-Create and use an impersonation token for a user:
+Create and use an impersonation token for a user::
 
-.. literalinclude:: users.py
-   :start-after: # it create
-   :end-before: # end it create
+    i_t = user.impersonationtokens.create({'name': 'token1', 'scopes': ['api']})
+    # use the token to create a new gitlab connection
+    user_gl = gitlab.Gitlab(gitlab_url, private_token=i_t.token)
 
-Revoke (delete) an impersonation token for a user:
+Revoke (delete) an impersonation token for a user::
 
-.. literalinclude:: users.py
-   :start-after: # it delete
-   :end-before: # end it delete
+    i_t.delete()
 
 Current User
 ============
@@ -162,22 +146,15 @@ References
   + :class:`gitlab.v4.objects.CurrentUserManager`
   + :attr:`gitlab.Gitlab.user`
 
-* v3 API:
-
-  + :class:`gitlab.v3.objects.CurrentUser`
-  + :class:`gitlab.v3.objects.CurrentUserManager`
-  + :attr:`gitlab.Gitlab.user`
-
 * GitLab API: https://docs.gitlab.com/ce/api/users.html
 
 Examples
 --------
 
-Get the current user:
+Get the current user::
 
-.. literalinclude:: users.py
-   :start-after: # currentuser get
-   :end-before: # end currentuser get
+    gl.auth()
+    current_user = gl.user
 
 GPG keys
 ========
@@ -202,29 +179,24 @@ are admin.
 Exemples
 --------
 
-List GPG keys for a user:
+List GPG keys for a user::
 
-.. literalinclude:: users.py
-   :start-after: # gpgkey list
-   :end-before: # end gpgkey list
+    gpgkeys = user.gpgkeys.list()
 
-Get a GPG gpgkey for a user:
+Get a GPG gpgkey for a user::
 
-.. literalinclude:: users.py
-   :start-after: # gpgkey get
-   :end-before: # end gpgkey get
+    gpgkey = user.gpgkeys.get(1)
 
-Create a GPG gpgkey for a user:
+Create a GPG gpgkey for a user::
 
-.. literalinclude:: users.py
-   :start-after: # gpgkey create
-   :end-before: # end gpgkey create
+    # get the key with `gpg --export -a GPG_KEY_ID`
+    k = user.gpgkeys.create({'key': public_key_content})
 
-Delete a GPG gpgkey for a user:
+Delete a GPG gpgkey for a user::
 
-.. literalinclude:: users.py
-   :start-after: # gpgkey delete
-   :end-before: # end gpgkey delete
+    user.gpgkeys.delete(1)
+    # or
+    gpgkey.delete()
 
 SSH keys
 ========
@@ -244,45 +216,25 @@ are admin.
   + :class:`gitlab.v4.objects.UserKeyManager`
   + :attr:`gitlab.v4.objects.User.keys`
 
-* v3 API:
-
-  + :class:`gitlab.v3.objects.CurrentUserKey`
-  + :class:`gitlab.v3.objects.CurrentUserKeyManager`
-  + :attr:`gitlab.v3.objects.CurrentUser.keys`
-  + :attr:`gitlab.Gitlab.user.keys`
-  + :class:`gitlab.v3.objects.UserKey`
-  + :class:`gitlab.v3.objects.UserKeyManager`
-  + :attr:`gitlab.v3.objects.User.keys`
-  + :attr:`gitlab.Gitlab.user_keys`
-
 * GitLab API: https://docs.gitlab.com/ce/api/users.html#list-ssh-keys
 
 Exemples
 --------
 
-List SSH keys for a user:
+List SSH keys for a user::
 
-.. literalinclude:: users.py
-   :start-after: # key list
-   :end-before: # end key list
+    keys = user.keys.list()
 
-Get an SSH key for a user:
+Create an SSH key for a user::
 
-.. literalinclude:: users.py
-   :start-after: # key get
-   :end-before: # end key get
+    k = user.keys.create({'title': 'my_key',
+                          'key': open('/home/me/.ssh/id_rsa.pub').read()})
 
-Create an SSH key for a user:
+Delete an SSH key for a user::
 
-.. literalinclude:: users.py
-   :start-after: # key create
-   :end-before: # end key create
-
-Delete an SSH key for a user:
-
-.. literalinclude:: users.py
-   :start-after: # key delete
-   :end-before: # end key delete
+    user.keys.delete(1)
+    # or
+    key.delete()
 
 Emails
 ======
@@ -302,45 +254,30 @@ are admin.
   + :class:`gitlab.v4.objects.UserEmailManager`
   + :attr:`gitlab.v4.objects.User.emails`
 
-* v3 API:
-
-  + :class:`gitlab.v3.objects.CurrentUserEmail`
-  + :class:`gitlab.v3.objects.CurrentUserEmailManager`
-  + :attr:`gitlab.v3.objects.CurrentUser.emails`
-  + :attr:`gitlab.Gitlab.user.emails`
-  + :class:`gitlab.v3.objects.UserEmail`
-  + :class:`gitlab.v3.objects.UserEmailManager`
-  + :attr:`gitlab.v3.objects.User.emails`
-  + :attr:`gitlab.Gitlab.user_emails`
-
 * GitLab API: https://docs.gitlab.com/ce/api/users.html#list-emails
 
 Exemples
 --------
 
-List emails for a user:
+List emails for a user::
 
-.. literalinclude:: users.py
-   :start-after: # email list
-   :end-before: # end email list
+    emails = user.emails.list()
 
-Get an email for a user:
+Get an email for a user::
 
-.. literalinclude:: users.py
-   :start-after: # email get
-   :end-before: # end email get
+    email = gl.user_emails.list(1, user_id=1)
+    # or
+    email = user.emails.get(1)
 
-Create an email for a user:
+Create an email for a user::
 
-.. literalinclude:: users.py
-   :start-after: # email create
-   :end-before: # end email create
+    k = user.emails.create({'email': 'foo@bar.com'})
 
-Delete an email for a user:
+Delete an email for a user::
 
-.. literalinclude:: users.py
-   :start-after: # email delete
-   :end-before: # end email delete
+    user.emails.delete(1)
+    # or
+    email.delete()
 
 Users activities
 ================
@@ -348,7 +285,6 @@ Users activities
 References
 ----------
 
-* v4 only
 * admin only
 
 * v4 API:
@@ -362,8 +298,6 @@ References
 Examples
 --------
 
-Get the users activities:
-
-.. code-block:: python
+Get the users activities::
 
-   activities = gl.user_activities.list(all=True, as_list=False)
+    activities = gl.user_activities.list(all=True, as_list=False)
diff --git a/docs/gl_objects/wikis.py b/docs/gl_objects/wikis.py
deleted file mode 100644
index 0c92fe6..0000000
--- a/docs/gl_objects/wikis.py
+++ /dev/null
@@ -1,21 +0,0 @@
-# list
-pages = project.wikis.list()
-# end list
-
-# get
-page = project.wikis.get(page_slug)
-# end get
-
-# create
-page = project.wikis.create({'title': 'Wiki Page 1',
-                             'content': open(a_file).read()})
-# end create
-
-# update
-page.content = 'My new content'
-page.save()
-# end update
-
-# delete
-page.delete()
-# end delete
diff --git a/docs/gl_objects/wikis.rst b/docs/gl_objects/wikis.rst
index 0934654..622c3a2 100644
--- a/docs/gl_objects/wikis.rst
+++ b/docs/gl_objects/wikis.rst
@@ -12,35 +12,29 @@ References
   + :class:`gitlab.v4.objects.ProjectWikiManager`
   + :attr:`gitlab.v4.objects.Project.wikis`
 
+* GitLab API: https://docs.gitlab.com/ce/api/wikis.html
+
 Examples
 --------
 
-Get the list of wiki pages for a project:
+Get the list of wiki pages for a project::
 
-.. literalinclude:: wikis.py
-   :start-after: # list
-   :end-before: # end list
+    pages = project.wikis.list()
 
-Get a single wiki page:
+Get a single wiki page::
 
-.. literalinclude:: wikis.py
-   :start-after: # get
-   :end-before: # end get
+    page = project.wikis.get(page_slug)
 
-Create a wiki page:
+Create a wiki page::
 
-.. literalinclude:: wikis.py
-   :start-after: # create
-   :end-before: # end create
+    page = project.wikis.create({'title': 'Wiki Page 1',
+                                 'content': open(a_file).read()})
 
-Update a wiki page:
+Update a wiki page::
 
-.. literalinclude:: wikis.py
-   :start-after: # update
-   :end-before: # end update
+    page.content = 'My new content'
+    page.save()
 
-Delete a wiki page:
+Delete a wiki page::
 
-.. literalinclude:: wikis.py
-   :start-after: # delete
-   :end-before: # end delete
+    page.delete()