4 files changed, 82 insertions, 0 deletions

diff --git a/docs/api-objects.rst b/docs/api-objects.rst
new file mode 100644
index 0000000..7b5d40b
--- /dev/null
+++ b/docs/api-objects.rst
@@ -0,0 +1,7 @@
+########################
+API objects manipulation
+########################
+
+.. toctree::
+
+   gl_objects/branches
diff --git a/docs/gl_objects/branches.py b/docs/gl_objects/branches.py
new file mode 100644
index 0000000..b485ee0
--- /dev/null
+++ b/docs/gl_objects/branches.py
@@ -0,0 +1,33 @@
+# 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
+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()
+# end delete
+
+# protect
+branch.protect()
+branch.unprotect()
+# end protect
diff --git a/docs/gl_objects/branches.rst b/docs/gl_objects/branches.rst
new file mode 100644
index 0000000..9ec6860
--- /dev/null
+++ b/docs/gl_objects/branches.rst
@@ -0,0 +1,41 @@
+########
+Branches
+########
+
+Use :class:`ProjectBranch` objects to manipulate repository branches.
+
+To create :class:`ProjectBranch` objects use the
+:class:`Gitlab.project_branches` or :class:`Project.branches` managers.
+
+Examples
+========
+
+Get the list of branches for a repository:
+
+.. literalinclude:: branches.py
+   :start-after: # list
+   :end-before: # end list
+
+Get a single repository branch:
+
+.. literalinclude:: branches.py
+   :start-after: # get
+   :end-before: # end get
+
+Create a repository branch:
+
+.. literalinclude:: branches.py
+   :start-after: # create
+   :end-before: # end create
+
+Delete a repository branch:
+
+.. literalinclude:: branches.py
+   :start-after: # delete
+   :end-before: # end delete
+
+Protect/unprotect a repository branch:
+
+.. literalinclude:: branches.py
+   :start-after: # protect
+   :end-before: # end protect
diff --git a/docs/index.rst b/docs/index.rst
index 2fa45da..f38aea8 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,6 +14,7 @@ Contents:
    install
    cli
    api-usage
+   api-objects
    faq
    upgrade-from-0.10
    api/modules