docs: add milestones API

3 files changed, 98 insertions, 0 deletions

diff --git a/docs/api-objects.rst b/docs/api-objects.rst
index 83aaa20..5c92021 100644
--- a/docs/api-objects.rst
+++ b/docs/api-objects.rst
@@ -16,6 +16,7 @@ API objects manipulation
    gl_objects/licenses
    gl_objects/mrs
    gl_objects/namespaces
+   gl_objects/milestones
    gl_objects/projects
    gl_objects/runners
    gl_objects/users
diff --git a/docs/gl_objects/milestones.py b/docs/gl_objects/milestones.py
new file mode 100644
index 0000000..27be573
--- /dev/null
+++ b/docs/gl_objects/milestones.py
@@ -0,0 +1,42 @@
+# list
+milestones = gl.project_milestones.list(project_id=1)
+# or
+milestones = project.milestones.list()
+# end list
+
+# filter
+milestones = gl.project_milestones.list(project_id=1, state='closed')
+# or
+milestones = project.milestones.list(state='closed')
+# end filter
+
+# get
+milestone = gl.project_milestones.get(milestone_id, project_id=1)
+# or
+milestone = project.milestones.get(milestone_id)
+# end get
+
+# create
+milestone = gl.project_milestones.create({'title': '1.0'}, project_id=1)
+# or
+milestone = project.milestones.create({'title': '1.0'})
+# end create
+
+# update
+milestone.description = 'v 1.0 release'
+milestone.save()
+# end update
+
+# state
+# close a milestone
+milestone.state_event = 'close'
+milestone.save
+
+# activate a milestone
+milestone.state_event = 'activate'
+m.save()
+# end state
+
+# issues
+issues = milestone.issues()
+# end issues
diff --git a/docs/gl_objects/milestones.rst b/docs/gl_objects/milestones.rst
new file mode 100644
index 0000000..db83275
--- /dev/null
+++ b/docs/gl_objects/milestones.rst
@@ -0,0 +1,55 @@
+##########
+Milestones
+##########
+
+Use :class:`~gitlab.objects.ProjectMilestone` objects to manipulate milestones.
+The :attr:`gitlab.Gitlab.project_milestones` and :attr:`Project.milestones
+<gitlab.objects.Project.milestones>` manager objects provide helper functions.
+
+Examples
+--------
+
+List the milestones for a project:
+
+.. literalinclude:: milestones.py
+   :start-after: # list
+   :end-before: # end list
+
+You can filter the list using the following parameters:
+
+* ``iid``: unique ID of the milestone for the project
+* ``state``: either ``active`` or ``closed``
+
+.. literalinclude:: milestones.py
+   :start-after: # filter
+   :end-before: # end filter
+
+Get a single milestone:
+
+.. literalinclude:: milestones.py
+   :start-after: # get
+   :end-before: # end get
+
+Create a milestone:
+
+.. literalinclude:: milestones.py
+   :start-after: # create
+   :end-before: # end create
+
+Edit a milestone:
+
+.. literalinclude:: milestones.py
+   :start-after: # update
+   :end-before: # end update
+
+Change the state of a milestone (activate / close):
+
+.. literalinclude:: milestones.py
+   :start-after: # state
+   :end-before: # end state
+
+List the issues related to a milestone:
+
+.. literalinclude:: milestones.py
+   :start-after: # issues
+   :end-before: # end issues