doc(api): Add documentation for iterations

PPaques · PPaques · commit 3365cc106b4f · 2020-11-30T21:08:21.000+01:00
diff --git a/docs/api-objects.rst b/docs/api-objects.rst
@@ -24,6 +24,7 @@ API examples
    gl_objects/geo_nodes
    gl_objects/groups
    gl_objects/issues
+   gl_objects/iterations
    gl_objects/boards
    gl_objects/labels
    gl_objects/notifications
diff --git a/docs/gl_objects/iterations.rst b/docs/gl_objects/iterations.rst
@@ -0,0 +1,63 @@
+##########
+Iterations
+##########
+
+Project Iterations
+==================
+
+Reference
+---------
+
+* v4 API:
+
+  + :class:`gitlab.v4.objects.ProjectIteration`
+  + :class:`gitlab.v4.objects.ProjectIterationManager`
+  + :attr:`gitlab.v4.objects.Project.iterations`
+
+  + :class:`gitlab.v4.objects.GroupIteration`
+  + :class:`gitlab.v4.objects.GroupIterationManager`
+  + :attr:`gitlab.v4.objects.Group.iterations`
+
+* GitLab API:
+
+  + https://docs.gitlab.com/ee/api/iterations.html
+  + https://docs.gitlab.com/ee/api/group_iterations.html
+
+Examples
+--------
+
+List the iterations for a project or a group::
+
+    p_iterations = project.iterations.list()
+    g_iterations = group.iterations.list()
+
+You can filter the list using the following parameters:
+
+* ``iids``: unique IDs of iterations for the project
+* ``state``: either ``opened``, ``upcoming``, ``started``, ``closed``, or ``all`` iterations. Defaults to ``all``. 
+* ``search``: search only iterations with a title matching the provided string.
+
+
+::
+
+    p_iterationss = project.iterations.list(state='closed')
+    g_iterationss = group.iterations.list(state='opened')
+
+Get a single iteration::
+
+    p_iteration = project.iterations.get(interation_id)
+    g_iteration = group.iterations.get(interation_id)
+
+Create a iteration::
+
+    iteration = project.iterations.create({'title': 'Week 22-23'})
+
+Edit an interation::
+
+    iteration.description = 'v 1.0 release'
+    iterations.save()
+
+
+List the issues related to a milestone::
+
+    issues = iteration.issues()
