Update the objects doc/examples for v4

docs/gl_objects/access_requests.py

@@ -1,23 +1,14 @@
 # list
-p_ars = gl.project_accessrequests.list(project_id=1)
-g_ars = gl.group_accessrequests.list(group_id=1)
-# or
 p_ars = project.accessrequests.list()
 g_ars = group.accessrequests.list()
 # end list
 
 # get
-p_ar = gl.project_accessrequests.get(user_id, project_id=1)
-g_ar = gl.group_accessrequests.get(user_id, group_id=1)
-# or
 p_ar = project.accessrequests.get(user_id)
 g_ar = group.accessrequests.get(user_id)
 # end get
 
 # create
-p_ar = gl.project_accessrequests.create({}, project_id=1)
-g_ar = gl.group_accessrequests.create({}, group_id=1)
-# or
 p_ar = project.accessrequests.create({})
 g_ar = group.accessrequests.create({})
 # end create
@@ -28,9 +19,6 @@
 # end approve
 
 # delete
-gl.project_accessrequests.delete(user_id, project_id=1)
-gl.group_accessrequests.delete(user_id, group_id=1)
-# or
 project.accessrequests.delete(user_id)
 group.accessrequests.delete(user_id)
 # or

docs/gl_objects/access_requests.rst

@@ -2,14 +2,41 @@
 Access requests
 ###############
 
-Use :class:`~gitlab.objects.ProjectAccessRequest` and
-:class:`~gitlab.objects.GroupAccessRequest` objects to manipulate access
-requests for projects and groups. The
-:attr:`gitlab.Gitlab.project_accessrequests`,
-:attr:`gitlab.Gitlab.group_accessrequests`, :attr:`Project.accessrequests
-<gitlab.objects.Project.accessrequests>` and :attr:`Group.accessrequests
-<gitlab.objects.Group.accessrequests>` manager objects provide helper
-functions.
+Users can request access to groups and projects.
+
+When access is granted the user should be given a numerical access level. The
+following constants are provided to represent the access levels:
+
+* ``gitlab.GUEST_ACCESS``: ``10``
+* ``gitlab.REPORTER_ACCESS``: ``20``
+* ``gitlab.DEVELOPER_ACCESS``: ``30``
+* ``gitlab.MASTER_ACCESS``: ``40``
+* ``gitlab.OWNER_ACCESS``: ``50``
+
+References
+----------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectAccessRequest`
+  + :class:`gitlab.v4.objects.ProjectAccessRequestManager`
+  + :attr:`gitlab.v4.objects.Project.accessrequests`
+  + :class:`gitlab.v4.objects.GroupAccessRequest`
+  + :class:`gitlab.v4.objects.GroupAccessRequestManager`
+  + :attr:`gitlab.v4.objects.Group.accessrequests`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectAccessRequest`
+  + :class:`gitlab.v3.objects.ProjectAccessRequestManager`
+  + :attr:`gitlab.v3.objects.Project.accessrequests`
+  + :attr:`gitlab.Gitlab.project_accessrequests`
+  + :class:`gitlab.v3.objects.GroupAccessRequest`
+  + :class:`gitlab.v3.objects.GroupAccessRequestManager`
+  + :attr:`gitlab.v3.objects.Group.accessrequests`
+  + :attr:`gitlab.Gitlab.group_accessrequests`
+
+* GitLab API: https://docs.gitlab.com/ce/api/access_requests.html
 
 Examples
 --------

docs/gl_objects/branches.py

@@ -1,27 +1,22 @@
 # list
-branches = gl.project_branches.list(project_id=1)
-# or
 branches = project.branches.list()
 # end list
 
 # get
-branch = gl.project_branches.get(project_id=1, id='master')
-# or
 branch = project.branches.get('master')
 # end get
 
 # create
-branch = gl.project_branches.create({'branch_name': 'feature1',
-                                     'ref': 'master'},
-                                    project_id=1)
-# or
+# v4
+branch = project.branches.create({'branch': 'feature1',
+                                  'ref': 'master'})
+
+#v3
 branch = project.branches.create({'branch_name': 'feature1',
                                   'ref': 'master'})
 # end create
 
 # delete
-gl.project_branches.delete(project_id=1, id='feature1')
-# or
 project.branches.delete('feature1')
 # or
 branch.delete()

docs/gl_objects/branches.rst

@@ -2,15 +2,25 @@
 Branches
 ########
 
-Use :class:`~gitlab.objects.ProjectBranch` objects to manipulate repository
-branches.
+References
+----------
 
-To create :class:`~gitlab.objects.ProjectBranch` objects use the
-:attr:`gitlab.Gitlab.project_branches` or :attr:`Project.branches
-<gitlab.objects.Project.branches>` managers.
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectBranch`
+  + :class:`gitlab.v4.objects.ProjectBranchManager`
+  + :attr:`gitlab.v4.objects.Project.branches`
+
+* v3 API:
+
+  + :class:`gitlab.v3.objects.ProjectBranch`
+  + :class:`gitlab.v3.objects.ProjectBranchManager`
+  + :attr:`gitlab.v3.objects.Project.branches`
+
+* GitLab API: https://docs.gitlab.com/ce/api/branches.html
 
 Examples
-========
+--------
 
 Get the list of branches for a repository:
 
@@ -41,10 +51,13 @@ Protect/unprotect a repository branch:
 .. literalinclude:: branches.py
    :start-after: # protect
    :end-before: # end protect
-   
+
 .. note::
-
-   By default, developers will not be able to push or merge into
-   protected branches. This can be changed by passing ``developers_can_push``
-   or ``developers_can_merge`` like so: 
-   ``branch.protect(developers_can_push=False, developers_can_merge=True)``
+
+   By default, developers are not authorized to push or merge into protected
+   branches. This can be changed by passing ``developers_can_push`` or
+   ``developers_can_merge``:
+
+   .. code-block:: python
+
+      branch.protect(developers_can_push=True, developers_can_merge=True)

docs/gl_objects/builds.py

@@ -1,19 +1,12 @@
 # var list
-variables = gl.project_variables.list(project_id=1)
-# or
 variables = project.variables.list()
 # end var list
 
 # var get
-var = gl.project_variables.get(var_key, project_id=1)
-# or
 var = project.variables.get(var_key)
 # end var get
 
 # var create
-var = gl.project_variables.create({'key': 'key1', 'value': 'value1'},
-                                  project_id=1)
-# or
 var = project.variables.create({'key': 'key1', 'value': 'value1'})
 # end var create
 
@@ -23,58 +16,47 @@
 # end var update
 
 # var delete
-gl.project_variables.delete(var_key)
-# or
-project.variables.delete()
+project.variables.delete(var_key)
 # or
 var.delete()
 # end var delete
 
 # trigger list
-triggers = gl.project_triggers.list(project_id=1)
-# or
 triggers = project.triggers.list()
 # end trigger list
 
 # trigger get
-trigger = gl.project_triggers.get(trigger_token, project_id=1)
-# or
 trigger = project.triggers.get(trigger_token)
 # end trigger get
 
 # trigger create
-trigger = gl.project_triggers.create({}, project_id=1)
-# or
 trigger = project.triggers.create({})
 # end trigger create
 
 # trigger delete
-gl.project_triggers.delete(trigger_token)
-# or
-project.triggers.delete()
+project.triggers.delete(trigger_token)
 # or
 trigger.delete()
 # end trigger delete
 
 # list
-builds = gl.project_builds.list(project_id=1)
-# or
-builds = project.builds.list()
+builds = project.builds.list()  # v3
+jobs = project.jobs.list()  # v4
 # end list
 
 # commit list
+# v3 only
 commit = gl.project_commits.get(commit_sha, project_id=1)
 builds = commit.builds()
 # end commit list
 
 # get
-build = gl.project_builds.get(build_id, project_id=1)
-# or
-project.builds.get(build_id)
+project.builds.get(build_id)  # v3
+project.jobs.get(job_id)  # v4
 # end get
 
 # artifacts
-build.artifacts()
+build_or_job.artifacts()
 # end artifacts
 
 # stream artifacts
@@ -86,33 +68,32 @@ def __call__(self, chunk):
         self._fd.write(chunk)
 
 target = Foo()
-build.artifacts(streamed=True, action=target)
+build_or_job.artifacts(streamed=True, action=target)
 del(target)  # flushes data on disk
 # end stream artifacts
 
 # keep artifacts
-build.keep_artifacts()
+build_or_job.keep_artifacts()
 # end keep artifacts
 
 # trace
-build.trace()
+build_or_job.trace()
 # end trace
 
 # retry
-build.cancel()
-build.retry()
+build_or_job.cancel()
+build_or_job.retry()
 # end retry
 
 # erase
-build.erase()
+build_or_job.erase()
 # end erase
 
 # play
-build.play()
+build_or_job.play()
 # end play
 
 # trigger run
-p = gl.projects.get(project_id)
-p.trigger_build('master', trigger_token,
-                {'extra_var1': 'foo', 'extra_var2': 'bar'})
+project.trigger_build('master', trigger_token,
+                      {'extra_var1': 'foo', 'extra_var2': 'bar'})
 # end trigger run