Component callback docs, small fix (#217)

* Fixed PartialEmoji usage in create_button

* Include component callbacks in docs, patch some things in component docs.

* Apply suggestions from code review

Co-authored-by: LordOfPolls <[email protected]>

* Add subsections

* Applied suggestions from reviews

Co-authored-by: LordOfPolls <[email protected]>

Author: artem30801

discord_slash/utils/manage_components.py

@@ -82,6 +82,8 @@ def emoji_to_dict(emoji: typing.Union[discord.Emoji, discord.PartialEmoji, str])
     """
     if isinstance(emoji, discord.Emoji):
         emoji = {"name": emoji.name, "id": emoji.id, "animated": emoji.animated}
+    elif isinstance(emoji, discord.PartialEmoji):
+        emoji = emoji.to_dict()
     elif isinstance(emoji, str):
         emoji = {"name": emoji, "id": None}
     return emoji if emoji else {}

docs/components.rst

@@ -45,28 +45,51 @@ Well, in Discord, clicking buttons and using slash commands are called ``interac
 Responding to interactions
 __________________________
 
-When responding, you have 2 choices in how you handle interactions. You can either wait for them in the command itself, or listen for them in a global event handler (similar to :meth:`on_slash_command_error`)
+When responding, you have 3 choices in how you handle interactions. You can either wait for them in the command itself, or listen for them in a global event handler (similar to :func:`on_slash_command_error`), or register async function as component callback.
 
-Lets go through the most common method first, responding in the event itself. We simply need to :meth:`wait_for` the event, just like you do for reactions. For this we're going to use :func:`wait_for_component() <discord_slash.utils.manage_components>`, and we're going to only wait for events from the action row we just .
-This method will return a :class:`ComponentContext <discord_slash.context.ComponentContext>` object that we can use to respond. For this example, we'll just edit the original message (:meth:`edit_origin() <discord_slash.context.ComponentContext.edit_origin>`)
+Wait_for
+********
+
+Lets go through the most common method first, responding in the command itself. We simply need to :func:`wait_for` the event, just like you do for reactions. For this we're going to use :func:`wait_for_component() <discord_slash.utils.manage_components>`, and we're going to only wait for events from the action row we just sent.
+This method will return a :class:`ComponentContext <discord_slash.context.ComponentContext>` object that we can use to respond. For this example, we'll just edit the original message (:meth:`edit_origin() <discord_slash.context.ComponentContext.edit_origin>`, uses same logic as :func:`edit()`)
 
 .. code-block:: python
 
     await ctx.send("My Message", components=[action_row])
     # note: this will only catch one button press, if you want more, put this in a loop
-    button_ctx: ComponentContext = await manage_components.wait_for_component(bot, action_row)
+    button_ctx: ComponentContext = await manage_components.wait_for_component(bot, components=action_row)
     await button_ctx.edit_origin(content="You pressed a button!")
 
 .. note:: It's worth being aware that if you handle the event in the command itself, it will not persist reboots. As such when you restart the bot, the interaction will fail
 
-Next we'll go over the alternative, a global event handler. This works just the same as :meth:`on_slash_command_error` or `on_ready`.
+Global event handler
+********************
+
+Next we'll go over the alternative, a global event handler. This works just the same as :func:`on_slash_command_error` or `on_ready`. But note that this code will be triggered on any components interaction.
 
 .. code-block:: python
 
     @bot.event
     async def on_component(ctx: ComponentContext):
+        # you may want to filter or change behaviour based on custom_id or message
         await ctx.edit_origin(content="You pressed a button!")
 
+Component callbacks
+********************
+
+There is one more method - making a function that'll be component callback - triggered when components in specified messages or with specified custom_ids would be activated
+Let's register our callback function via decorator :meth:`component_callback() <discord_slash.client.SlashCommand.component_callback>`, in similar ways to slash commands.
+
+.. code-block:: python
+
+    @slash.component_callback()
+    async def hello(button_context: ComponentContext):
+        await ctx.edit_origin(content="You pressed a button!")
+
+In this example, :func:`hello` will be triggered when you receive interaction event from a component with a `custom_id` set to `"hello"`. Just like slash commands, The callback's `custom_id` defaults to the function name.
+You can also register such callbacks in cogs using :func:`cog_component() <discord_slash.cog_ext>`
+Additionally, component callbacks can be dynamically added, removed or edited - see :class:`SlashCommand <discord_slash.client.SlashCommand>`
+
 But [writer], I dont want to edit the message
 *********************************************