docs: add labales API

Gauvain Pocentek · Gauvain Pocentek · commit 31882b8a57f3 · 2016-08-06T22:04:00.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -12,6 +12,7 @@ API objects manipulation
    gl_objects/environments
    gl_objects/groups
    gl_objects/issues
+   gl_objects/labels
    gl_objects/namespaces
    gl_objects/projects
    gl_objects/runners
diff --git a/docs/gl_objects/labels.py b/docs/gl_objects/labels.py
@@ -0,0 +1,35 @@
+# list
+labels = gl.project_labels.list(project_id=1)
+# or
+labels = project.labels.list()
+# end list
+
+# get
+label = gl.project_labels.get(label_name, project_id=1)
+# or
+label = project.labels.get(label_name)
+# end get
+
+# create
+label = gl.project_labels.create({'name': 'foo', 'color': '#8899aa'},
+                                 project_id=1)
+# or
+label = project.labels.create({'name': 'foo', 'color': '#8899aa'})
+# end create
+
+# update
+# change the name of the label:
+label.new_name = 'bar'
+label.save()
+# change its color:
+label.color = '#112233'
+label.save()
+# end update
+
+# delete
+gl.project_labels.delete(label_id, project_id=1)
+# or
+project.labels.list(label_id)
+# or
+label.delete()
+# end delete
diff --git a/docs/gl_objects/labels.rst b/docs/gl_objects/labels.rst
@@ -0,0 +1,40 @@
+######
+Labels
+######
+
+Use :class:`~gitlab.objects.ProjectLabel` objects to manipulate labels for
+projects. The :attr:`gitlab.Gitlab.project_labels` and :attr:`Project.labels
+<gitlab.objects.Project.labels>` manager objects provide helper functions.
+
+Examples
+--------
+
+List labels for a project:
+
+.. literalinclude:: labels.py
+   :start-after: # list
+   :end-before: # end list
+
+Get a single label:
+
+.. literalinclude:: labels.py
+   :start-after: # get
+   :end-before: # end get
+
+Create a label for a project:
+
+.. literalinclude:: labels.py
+   :start-after: # create
+   :end-before: # end create
+
+Update a label for a project:
+
+.. literalinclude:: labels.py
+   :start-after: # update
+   :end-before: # end update
+
+Delete a label for a project:
+
+.. literalinclude:: labels.py
+   :start-after: # delete
+   :end-before: # end delete
