docs: document projects API

Gauvain Pocentek · Gauvain Pocentek · commit 967595f504b8 · 2016-07-16T18:55:59.000+02:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -5,4 +5,5 @@ API objects manipulation
 .. toctree::
 
    gl_objects/branches
+   gl_objects/projects
    gl_objects/users
diff --git a/docs/gl_objects/projects.py b/docs/gl_objects/projects.py
@@ -0,0 +1,67 @@
+# list
+# Active projects
+projects = gl.projects.list()
+# Archived projects
+projects = gl.projects.list(archived=1)
+# Limit to projects with a defined visibility
+projects = gl.projects.list(visibility='public')
+
+# List owned projects
+projects = gl.projects.owned()
+
+# List starred projects
+projects = gl.projects.starred()
+
+# List all the projects
+projects = gl.projects.all()
+# end list
+
+# get
+# Get a project by ID
+project = gl.projects.get(10)
+# Get a project by userspace/name
+project = gl.projects.get('myteam/myproject')
+# end get
+
+# create
+project = gl.projects.create({'name': 'project1'})
+# end create
+
+# user create
+alice gl.users.list(username='alice')[0]
+user_project = gl.user_projects.create({'name': 'project',
+                                        'user_id': alice.id})
+# end user create
+
+# update
+project.snippets_enabled = 1
+project.save()
+# end update
+
+# delete
+gl.projects.delete(1)
+# or
+project.delete()
+# end delete
+
+# fork
+fork = gl.project_forks.create(project_id=1)
+# or
+fork = project.fork()
+# end fork
+
+# star
+p.star()
+p.unstar()
+# end star
+
+# archive
+p.archive_()
+p.unarchive_()
+# end archive
+
+# events list
+gl.project_events.list(project_id=1)
+# or
+project.events.list()
+# end events list
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
@@ -0,0 +1,96 @@
+########
+Projects
+########
+
+Use :class:`~gitlab.objects.Project` objects to manipulate projects. The
+:attr:`gitlab.Gitlab.projects` manager objects provides helper functions.
+
+Examples
+========
+
+List projects:
+
+The API provides several filtering parameters for the listing methods:
+
+* ``archived``: if ``True`` only archived projects will be returned
+* ``visibility``: returns only projects with the specified visibility (can be
+  ``public``, ``internal`` or ``private``)
+* ``search``: returns project matching the given pattern
+
+Results can also be sorted using the following parameters:
+
+* ``order_by``: sort using the given argument. Valid values are ``id``,
+  ``name``, ``path``, ``created_at``, ``updated_at`` and ``last_activity_at``.
+  The default is to sort by ``created_at``
+* ``sort``: sort order (``asc`` or ``desc``)
+
+.. literalinclude:: projects.py
+   :start-after: # list
+   :end-before: # end list
+
+Get a single project:
+
+.. literalinclude:: projects.py
+   :start-after: # get
+   :end-before: # end get
+
+Create a project:
+
+.. literalinclude:: projects.py
+   :start-after: # create
+   :end-before: # end create
+
+Create a project for a user (admin only):
+
+.. literalinclude:: projects.py
+   :start-after: # user create
+   :end-before: # end user create
+
+Update a project:
+
+.. literalinclude:: projects.py
+   :start-after: # update
+   :end-before: # end update
+
+Delete a project:
+
+.. literalinclude:: projects.py
+   :start-after: # delete
+   :end-before: # end delete
+
+Fork a project :
+
+.. literalinclude:: projects.py
+   :start-after: # fork
+   :end-before: # end fork
+
+Star/unstar a project:
+
+.. literalinclude:: projects.py
+   :start-after: # star
+   :end-before: # end star
+
+Archive/unarchive a project:
+
+.. literalinclude:: projects.py
+   :start-after: # archive
+   :end-before: # end archive
+
+.. note::
+
+   The underscore character at the end of the methods is used to workaround a
+   conflict with a previous misuse of the ``archive`` method (deprecated but
+   not yet removed).
+
+Events
+------
+
+Use :class:`~gitlab.objects.ProjectEvent` objects to manipulate projects. The
+:attr:`gitlab.Gitlab.project_events` and :attr:`Project.events
+<gitlab.objects.Project.events>` manager objects provide helper functions.
+
+List the project events:
+
+.. literalinclude:: projects.py
+   :start-after: # events list
+   :end-before: # end events list
diff --git a/docs/gl_objects/users.py b/docs/gl_objects/users.py
@@ -10,7 +10,7 @@
 # by ID
 user = gl.users.get(2)
 # by username
-user = gl.users.list(username='root')
+user = gl.users.list(username='root')[0]
 # end get
 
 # create
