From 8d03fef566b5702d3bd244314c6cab53a36dc4f6 Mon Sep 17 00:00:00 2001 From: kreusada <67752638+kreusada@users.noreply.github.com> Date: Wed, 3 Mar 2021 19:19:33 +0000 Subject: [PATCH] [Docs] Image Cog Guide (#4821) * [Docs] Images Cog Guide * [Docs] Image Cog Guide * Fixes for directory inside the index * The cog is cakked IMAGE not IMAGES * Potential fixes for failing checks * Grammar fixes * Some formatting updates * Fix merge conflicts from 3.4.7 * Re-format for requested changes --- docs/cog_guides/image.rst | 205 ++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 206 insertions(+) create mode 100644 docs/cog_guides/image.rst diff --git a/docs/cog_guides/image.rst b/docs/cog_guides/image.rst new file mode 100644 index 000000000..8bb01099f --- /dev/null +++ b/docs/cog_guides/image.rst @@ -0,0 +1,205 @@ +.. _image: + +===== +Image +===== + +This is the cog guide for the image cog. You will +find detailed docs about usage and commands. + +``[p]`` is considered as your prefix. + +.. note:: To use this cog, load it by typing this:: + + [p]load image + +.. _image-usage: + +----- +Usage +----- + +This cog provides commands for retrieving pictures from +websites such as Giphy and Imgur. + +.. _image-commands: + +-------- +Commands +-------- + +Here's a list of all commands available for this cog. + +.. _image-command-gif: + +^^^ +gif +^^^ + +**Syntax** + +.. code-block:: none + + [p]gif + +**Description** + +Retrieve the first search result from Giphy. This command requires API tokens +to be set via the :ref:`giphycreds ` command. + +**Arguments** + +* ````: The keywords used to search Giphy. + +.. _image-command-gifr: + +^^^^ +gifr +^^^^ + +**Syntax** + +.. code-block:: none + + [p]gifr + +**Description** + +Retrieve a random GIF from a Giphy search. This command requires API tokens +to be set via the :ref:`giphycreds ` command. + +**Arguments** + +* ````: The keywords used to generate a random GIF. + +.. _image-command-imgur: + +^^^^^ +imgur +^^^^^ + +**Syntax** + +.. code-block:: none + + [p]imgur + +**Description** + +Retrieves pictures from Imgur. This command requires API tokens to be set +via the :ref:`imgurcreds ` command. + +.. _image-command-imgur-search: + +"""""""""""" +imgur search +"""""""""""" + +**Syntax** + +.. code-block:: none + + [p]imgur search [count=1] + +**Description** + +Search for pictures on Imgur. This command requires API tokens to be set +via the :ref:`imgurcreds ` command. + +**Arguments** + +* ``[count]``: How many images should be returned (maximum 5). Defaults to 1. + +* ````: The terms used to search Imgur. + +.. _image-command-imgur-subreddit: + +""""""""""""""" +imgur subreddit +""""""""""""""" + +**Syntax** + +.. code-block:: none + + [p]imgur subreddit [count=1] [sort_type=top] [window=day] + +**Description** + +Get images from a subreddit. This command requires API tokens to be set +via the :ref:`imgurcreds ` command. + +**Arguments** + +* ````: The subreddit to get images from. + +* ``[count]``: The number of images to return (maximum 5). Defaults to 1. + +* ``[sort_type]``: New, or top results. Defaults to top. + +* ``[window]``: The timeframe, can be the past day, week, month, year or all. Defaults to day. + +.. _image-command-giphycreds: + +^^^^^^^^^^ +giphycreds +^^^^^^^^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]giphycreds + +**Description** + +Explains how to set GIPHY API tokens. + +**Getting your API key** + +1. Login (or create) a GIPHY account. +2. Visit `this page `__. +3. Press 'Create an App'. +4. Click 'Select API', and then 'Next Step'. +5. Add an app name, for example 'Red'. +6. Add an app description, for example 'Used for Red's image cog'. +7. Click 'Create App'. You'll need to agree to the GIPHY API terms. +8. Copy the API Key. +9. In Discord, run the following command:: + + [p]set api GIPHY api_key + +.. _image-command-imgurcreds: + +^^^^^^^^^^ +imgurcreds +^^^^^^^^^^ + +.. note:: |owner-lock| + +**Syntax** + +.. code-block:: none + + [p]imgurcreds + +**Description** + +Explains how to set Imgur API tokens. + +**Getting your API key** + +1. Login to (or create) an Imgur account. +2. Visit `this page `__. +3. Add an app name for your application, for example 'Red'. +4. Select 'Anonymous usage without user authorization' for the auth type. +5. Set the authorization callback URL to ``https://localhost`` +6. Leave the app website blank. +7. Enter a valid email address and a description. +8. Check the captcha box and click next. +9. Your Client ID will be on the next page. +10. In Discord, run the following command:: + + [p]set api imgur client_id diff --git a/docs/index.rst b/docs/index.rst index 3c37b9daa..451a0c135 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,6 +42,7 @@ Welcome to Red - Discord Bot's documentation! cog_guides/economy cog_guides/filter cog_guides/general + cog_guides/image cog_guides/streams cog_guides/trivia red_core_data_statement