docs: project repository API

Gauvain Pocentek · Gauvain Pocentek · commit 71a2a4fb8432 · 2016-08-09T16:07:25.000+02:00
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
@@ -150,3 +150,47 @@
 # 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
+file_content = p.repository_blob('master', 'README.rst')
+# 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 i in commit:
+    print(result.commits)
+
+# get the diffs
+for file_diff in commit.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
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
@@ -88,6 +88,57 @@ Archive/unarchive a project:
    conflict with a previous misuse of the ``archive`` method (deprecated but
    not yet removed).
 
+Repository
+----------
+
+The following examples show how you can manipulate the project code repository.
+
+List the repository tree:
+
+.. literalinclude:: projects.py
+   :start-after: # repository tree
+   :end-before: # end repository tree
+
+Get the content of a file for a commit:
+
+.. literalinclude:: projects.py
+   :start-after: # repository blob
+   :end-before: # end repository blob
+
+Get the repository archive:
+
+.. literalinclude:: projects.py
+   :start-after: # repository archive
+   :end-before: # end repository archive
+
+.. 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:
+
+.. literalinclude:: projects.py
+   :start-after: # repository raw_blob
+   :end-before: # end repository raw_blob
+
+.. 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:
+
+.. literalinclude:: projects.py
+   :start-after: # repository compare
+   :end-before: # end repository compare
+
+Get a list of contributors for the repository:
+
+.. literalinclude:: projects.py
+   :start-after: # repository contributors
+   :end-before: # end repository contributors
+
 Events
 ------
 
