[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

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()

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::
 

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,32 +236,21 @@ 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
     job = pipeline.jobs.get(job_id)  # gets one job from pipeline
 
 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::