Added docs

Author: eunwoo1104

README.md

@@ -26,5 +26,5 @@ For now clone this repository and use `discod_slash` folder.
 (Maybe will upload this at PyPi soon)
 
 ## DOCS
-Not yet ready.  
+See the source code. Maybe will use sphinx soon?  
 See [discord-api-docs](https://github.com/discord/discord-api-docs/blob/feature/interactions/docs/interactions/Slash_Commands.md) for some more information.

discord_slash/__init__.py

@@ -1,25 +1,11 @@
 """
-MIT License
+discord-py-slash-command
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-Copyright (c) 2020 eunwoo1104
+Simple Discord Slash Command extension for discord.py
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+:copyright: (c) 2020 eunwoo1104
+:license: MIT
 """
 
 from .client import SlashCommand

discord_slash/client.py

@@ -7,31 +7,61 @@
 
 
 class SlashCommand:
+    """
+    Slash command extension class.
+
+    :param client: discord.py Bot class. Although it accepts :class:`discord.Client` at init, using it is not allowed since :class:`discord.Client` doesn't support :func:`add_listener`.
+    :type client: Union[discord.Client, discord.ext.commands.Bot]
+    """
     def __init__(self,
                  client: typing.Union[discord.Client,
                                       commands.Bot]
                  ):
         if isinstance(client, discord.Client) and not isinstance(client, commands.Bot):
-            raise Exception("Currently only ext.Bot is supported.")
+            raise Exception("Currently only commands.Bot is supported.")
         self._discord = client
         self.commands = {}
         self.http = http.SlashCommandRequest()
         self.logger = logging.getLogger("discord_slash")
         self._discord.add_listener(self.on_socket_response)
 
     def slash(self, name=None):
+        """
+        Decorator that registers coroutine as a slash command.\n
+        1 arg is required for ctx(:func:`discord_slash.model.SlashContext`), and if your slash command has some args, then those args are also required.\n
+        All args are passed in order.\n
+        Note that Role, User, and Channel types are passed as id, since API doesn't give type of the option for now.
+
+        :param name: Name of the slash command.
+        """
         def wrapper(cmd):
             self.commands[cmd.__name__ if not name else name] = cmd
             self.logger.debug(f"Added command `{cmd.__name__ if not name else name}`")
             return cmd
         return wrapper
 
     def process_options(self, options: dict) -> list:
+        """
+        Not ready.
+
+        :param options: Dict of options.
+        :type options: dict
+        :return: list
+        :raises: :class:`NotImplementedError` - This is still not implemented.
+        """
+        raise NotImplementedError
+
         for x in options:
             pass
         return []
 
     async def on_socket_response(self, msg):
+        """
+        This event listener is automatically registered at initialization of this class.\n
+        DO NOT MANUALLY REGISTER, OVERRIDE, OR WHATEVER ACTION TO THIS COROUTINE UNLESS YOU KNOW WHAT YOU ARE DOING.
+
+        :param msg: Gateway message.
+        """
         if msg["t"] != "INTERACTION_CREATE":
             return
         to_use = msg["d"]

discord_slash/error.py

@@ -0,0 +1,24 @@
+class SlashCommandError(Exception):
+    """
+    All exceptions of this extension can be captured with this.
+    Note that discord.py doesn't trigger `on_command_error` event.
+    """
+    pass
+
+
+class RequestFailure(SlashCommandError):
+    """
+    Request to Discord API has failed.
+    """
+    def __init__(self, status: int, msg: str):
+        self.status = status
+        self.msg = msg
+        super().__init__(f"Request failed with resp: {self.status} | {self.msg}")
+
+
+class IncorrectFormat(SlashCommandError):
+    """
+    Some formats are incorrect. See Discord API DOCS for proper format.
+    """
+    def __init__(self, msg: str):
+        super().__init__(msg)

discord_slash/http.py

@@ -1,14 +1,25 @@
 import aiohttp
+from .error import RequestFailure
 
 
 class SlashCommandRequest:
     def __init__(self):
         pass
 
     async def post(self, _resp, _id, token):
+        """
+        Sends command response POST request to Discord API.
+
+        :param _resp: Command response.
+        :type _resp: dict
+        :param _id: Command message id.
+        :param token: Command message token.
+        :return: True if succeeded.
+        :raises: :class:`error.RequestFailure` - Requesting to API has failed.
+        """
         req_url = f"https://discord.com/api/v8/interactions/{_id}/{token}/callback"
         async with aiohttp.ClientSession() as session:
             async with session.post(req_url, json=_resp) as resp:
                 if not 200 <= resp.status < 300:
-                    raise Exception(f"Request failed with resp: {resp.status} | {await resp.text()}")
+                    raise RequestFailure(resp.status, await resp.text())
                 return True

discord_slash/model.py

@@ -5,6 +5,10 @@
 
 
 class SlashContext:
+    """
+    Context of the slash command.\n
+    Kinda similar with discord.ext.commands.Context.
+    """
     def __init__(self,
                  _http: http.SlashCommandRequest,
                  _json: dict,
@@ -23,6 +27,19 @@ async def send(self,
                    text: str = "",
                    embeds: typing.List[discord.Embed] = None,
                    tts: bool = False):
+        """
+        Sends response of the slash command.
+
+        :param send_type: Type of the response. Refer Discord API DOCS for more info about types. Default `4`.
+        :type send_type: int
+        :param text: Text of the response. Can be `None`.
+        :type text: str
+        :param embeds: Embeds of the response. Maximum 10, can be empty.
+        :type embeds: List[discord.Embed]
+        :param tts: Whether to speak message using tts. Default `False`.
+        :type tts: bool
+        :return: `None`
+        """
         if embeds and len(embeds) > 10:
             raise
         base = {

discord_slash/utils/__init__.py

@@ -0,0 +1,9 @@
+"""
+discord-py-slash-command.utils
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Utility functions for slash command.
+
+:copyright: (c) 2020 eunwoo1104
+:license: MIT
+"""

discord_slash/utils/manage_commands.py

@@ -7,6 +7,17 @@ async def add_slash_command(bot_id,
                             cmd_name: str,
                             description: str,
                             options: list = None):
+    """
+    A coroutine that sends a slash command add request to Discord API.
+
+    :param bot_id: User ID of the bot.
+    :param bot_token: Token of the bot.
+    :param guild_id: ID of the guild to add command. Pass `None` to add global command.
+    :param cmd_name: Name of the command. Must be 3 or longer and 32 or shorter.
+    :param description: Description of the command.
+    :param options: List of the function.
+    :return: JSON Response of the request.
+    """
     url = f"https://discord.com/api/v8/applications/{bot_id}"
     url += "/commands" if not guild_id else f"/guilds/{guild_id}/commands"
     base = {
@@ -24,6 +35,15 @@ async def remove_slash_command(bot_id,
                                bot_token,
                                guild_id,
                                cmd_id):
+    """
+    A coroutine that sends a slash command remove request to Discord API.
+
+    :param bot_id: User ID of the bot.
+    :param bot_token: Token of the bot.
+    :param guild_id: ID of the guild to remove command. Pass `None` to remove global command.
+    :param cmd_id: ID of the command.
+    :return: Response code of the request.
+    """
     url = f"https://discord.com/api/v8/applications/{bot_id}"
     url += "/commands" if not guild_id else f"/guilds/{guild_id}/commands"
     url += f"/{cmd_id}"
@@ -36,7 +56,17 @@ def create_option(name: str,
                   description: str,
                   option_type: int,
                   required: bool,
-                  choices: list = None):
+                  choices: list = None) -> dict:
+    """
+    Creates option used for creating slash command.
+
+    :param name: Name of the option.
+    :param description: Descrption of the option.
+    :param option_type: Type of the option.
+    :param required: Whether this option is required.
+    :param choices: Choices of the option. Can be empty.
+    :return: dict
+    """
     return {
         "name": name,
         "description": description,
@@ -46,7 +76,14 @@ def create_option(name: str,
     }
 
 
-def create_choices(value: str, name: str):
+def create_choice(value: str, name: str):
+    """
+    Creates choices used for creating command option.
+
+    :param value: Value of the choice.
+    :param name: Name of the choice.
+    :return: dict
+    """
     return {
         "value": value,
         "name": name

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)