From fbf45a291916746e10f418e50993d34628bbcaa5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bruno=20Garc=C3=ADa?= <garciabruno@users.noreply.github.com>
Date: Tue, 7 Nov 2017 10:15:56 -0300
Subject: [PATCH] Docs for Twitch Clips API (#23)

* Added Clip as an API resource

* Add day as valid PERIODS value

* Twitch Clips API implementation

* Add Clips to TwitchClient

* Import clips

* Tests on Twitch Clips API

* Added test_get_top

* Renamed test name to follow standard

* E261: at least two spaces before inline comment

* Expected 2 blank lines

* Re-ordered imports

* Sorted imports

* Documentation for Clips API
---
 docs/api/clips.rst | 35 +++++++++++++++++++++++++++++++++++
 docs/index.rst     |  3 ++-
 2 files changed, 37 insertions(+), 1 deletion(-)
 create mode 100644 docs/api/clips.rst

diff --git a/docs/api/clips.rst b/docs/api/clips.rst
new file mode 100644
index 0000000..2dca0d9
--- /dev/null
+++ b/docs/api/clips.rst
@@ -0,0 +1,35 @@
+Clips
+====
+
+.. currentmodule:: twitch.api.clips
+
+.. class:: Clips()
+
+    This class provides methods for easy access to `Twitch Clips API`_.
+
+    .. classmethod:: get_by_slug(slug)
+
+        Gets a clip object based on the slug provided
+
+        :param string slug: Twitch Slug.
+
+
+    .. classmethod:: get_top(channel, cursor, game, language, limit, period, trending)
+
+        Gets all clips emoticons in one or more specified sets.
+
+        :param string channel: Channel name. If this is specified, top clips for only this channel are returned; otherwise, top clips for all channels are returned. If both channel and game are specified, game is ignored.
+        :param string cursor: Tells the server where to start fetching the next set of results, in a multi-page response.
+        :param string game: Game name. (Game names can be retrieved with the Search Games endpoint.) If this is specified, top clips for only this game are returned; otherwise, top clips for all games are returned. If both channel and game are specified, game is ignored.
+        :param string language: Comma-separated list of languages, which constrains the languages of videos returned. Examples: es, en,es,th. If no language is specified, all languages are returned.
+        :param int limit: Maximum number of most-recent objects to return. Default: 10. Maximum: 100.
+        :param string period: The window of time to search for clips. Valid values: day, week, month, all. Default: week.
+        :param boolean trending: If True, the clips returned are ordered by popularity; otherwise, by viewcount. Default: False.
+
+
+    .. classmethod:: get_followed()
+
+        Gets top clips for games followed by the user identified by OAuth token. Results are ordered by popularity.
+
+
+.. _`Twitch Clips API`: https://dev.twitch.tv/docs/v5/reference/clips
diff --git a/docs/index.rst b/docs/index.rst
index 2ba7e55..72d74b9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,7 +8,7 @@ An easy to use Python library for accessing the Twitch API
     This documentation is a work in progress
 
 .. note::
-    ``python-twitch-client`` currently supports Twitch API v5. 
+    ``python-twitch-client`` currently supports Twitch API v5.
 
     If you find a missing endpoint or a bug please raise an issue_ or contribute and open a
     `pull request`_.
@@ -65,6 +65,7 @@ Contents:
    :maxdepth: 2
 
    basic_usage
+   api/clips
    api/chat
    api/channel_feed
    api/channels