Update docs

Author: Kenny2github

discord/ext/slash/__init__.py

@@ -46,22 +46,30 @@ async def repeat( # command name
   Notably, ``ctx.message`` does not exist, because slash commands can be run
   completely without the involvement of messages. However, channel and author
   information is still available.
+* On the other hand, :class:`~discord.ext.slash.ComponentContext` does have a
+  :attr:`~discord.ext.slash.ComponentContext.message` attribute
+  available to message component callbacks.
 * All descriptions are **required**.
-* You must grant the bot ``applications.commands`` permissions in the OAuth2 section of the developer dashboard.
+* You must grant the bot ``applications.commands`` permissions in the OAuth2
+  section of the developer dashboard.
 
-See the `docs <https://discord-ext-slash.rtfd.io>`_.
+See the `docs <https://discord-ext-slash.rtfd.io>`_ as well as the
+`demo bot <https://github.com/Kenny2github/discord-ext-slash/blob/main/demo_bot.py>`_.
 '''
 from __future__ import annotations
 from .simples import (
     SlashWarning, ApplicationCommandOptionType,
     ApplicationCommandPermissionType, InteractionType, InteractionResponseType,
-    InteractionCallbackType, CallbackFlags, ChoiceEnum, ButtonStyle
+    InteractionCallbackType, CallbackFlags, ChoiceEnum, ButtonStyle,
+    PartialRole, PartialCategoryChannel, PartialMember, PartialObject,
+    PartialTextChannel, PartialVoiceChannel
 )
 from .option import Option, Choice
 from .components import (
     MessageComponent, ActionRow, Button,
     SelectMenu, SelectOption
 )
+from .message import ComponentedMessage
 from .command import (
     BaseCallback, Command, Group, cmd, group, permit,
     callback, CommandPermissionsDict, ComponentCallback

discord/ext/slash/bot.py

@@ -53,7 +53,7 @@ class SlashBot(commands.Bot):
         Create a :class:`Group` with the decorated coroutine and ``**kwargs``
         and add it to :attr:`slash`.
 
-    .. decoratormethod:: component_callback(matcher, ttl, **kwargs)
+    .. decoratormethod:: component_callback(matcher, ttl=15min, **kwargs)
 
         Create a :class:`ComponentCallback` with the decorated coroutine
         and ``**kwargs`` and add it to :attr:`comp_callbacks`.

discord/ext/slash/components.py

@@ -29,7 +29,7 @@ def to_dict(self) -> dict:
         return {'type': self.type}
 
 class ActionRow(MessageComponent):
-    """A container for other components.
+    r"""A container for other components.
 
     This can be instantiated either like
     ``ActionRow(component1, component2)``
@@ -39,9 +39,9 @@ class ActionRow(MessageComponent):
         The first of one or multiple subcomponents, *or*
         an iterable of subcomponents.
     :type first: Union[Button, SelectMenu, Iterable[Button]]
-    :param *args:
+    :param \*args:
         The rest of the subcomponents, if ``first`` is the first.
-    :type *args: Button
+    :type \*args: Button
 
     .. attribute:: components
         :type: list[Union[Button, SelectMenu]]
@@ -171,6 +171,16 @@ def to_dict(self) -> dict:
 class SelectMenu(MessageComponent):
     """A select menu for picking from choices.
 
+    When using this component, the values selected will be passed to the
+    callback as variable-count arguments, which must be received like so:
+
+    .. code-block:: python
+
+        @callback(menu_id)
+        async def menu_callback(ctx: ComponentContext, *values: str):
+            # values are now the string values of the options
+            # specified on the select menu
+
     .. attribute:: custom_id
         :type: str
 

discord/ext/slash/context.py

@@ -540,6 +540,10 @@ class ComponentContext(BaseContext):
     Attributes described below are in addition or in place of
     those defined in :class:`BaseContext`.
 
+    .. attribute:: message
+        :type: ComponentedMessage
+
+        The message that the component is attached to.
     .. attribute:: command
         :type: Optional[ComponentCallback]
 

discord/ext/slash/message.py

@@ -3,7 +3,7 @@
 from .components import MessageComponent
 
 class ComponentedMessage(discord.Message):
-    """Monkeypatch discord.py's Message to include components."""
+    """Monkeypatch :class:`discord.Message` to include components."""
 
     __slots__ = discord.Message.__slots__ + ('components',)
 

discord/ext/slash/simples.py

@@ -146,10 +146,20 @@ class ButtonStyle(IntEnum):
     """:class:`Button` appearance styles.
 
     .. attribute:: PRIMARY
+
+        Blurple primary-action button.
     .. attribute:: SECONDARY
+
+        Gray secondary-action button.
     .. attribute:: SUCCESS
+
+        Green confirmation button.
     .. attribute:: DANGER
+
+        Red destructive-action button.
     .. attribute:: LINK
+
+        Gray link button with link icon.
     """
     PRIMARY = 1
     SECONDARY = 2

docs/discord-ext-slash.rst

@@ -9,6 +9,7 @@ Decorators
 .. autodecorator:: cmd
 .. autodecorator:: group
 .. autodecorator:: permit
+.. autodecorator:: callback
 
 Classes
 -------
@@ -18,29 +19,55 @@ The Bot
 
 .. autoclass:: SlashBot
 
+Base Classes
+~~~~~~~~~~~~
+
+.. autoclass:: BaseContext
+.. autoclass:: BaseCallback
+.. autoclass:: MessageComponent
+
 Interaction Context
 ~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: Context
+   :show-inheritance:
 .. autoclass:: Interaction
+.. autoclass:: ComponentContext
+   :show-inheritance:
 
 Slash Commands
 ~~~~~~~~~~~~~~
 
 .. autoclass:: Command
+   :show-inheritance:
 .. autoclass:: Group
 
+
+Message Components
+~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: ComponentCallback
+.. autoclass:: ActionRow
+   :show-inheritance:
+.. autoclass:: Button
+   :show-inheritance:
+.. autoclass:: SelectMenu
+   :show-inheritance:
+.. autoclass:: SelectOption
+
 Data Classes
 ~~~~~~~~~~~~
 
 .. autoclass:: Option
 .. autoclass:: Choice
 
 Miscellaneous
-~~~~~~~~~~~~~
+-------------
 
 .. autoclass:: SlashWarning
 .. autoclass:: CommandPermissionsDict
+.. autoclass:: ComponentedMessage
+   :show-inheritance:
 
 Partial Objects
 ~~~~~~~~~~~~~~~
@@ -62,14 +89,15 @@ information that discord.py prefers (most notably guild information).
    :show-inheritance:
 
 Enums
------
+~~~~~
 
 .. autoclass:: ApplicationCommandOptionType
 .. autoclass:: ApplicationCommandPermissionType
 .. autoclass:: InteractionCallbackType
+.. autoclass:: InteractionResponseType
 .. autoclass:: CallbackFlags
-.. autoclass:: MessageFlags
 .. autoclass:: ChoiceEnum
+.. autoclass:: ButtonStyle
 
 Events
 ------
@@ -83,7 +111,7 @@ Events
    Triggered immediately after :meth:`SlashBot.register_commands` to give an
    opportunity to register dynamic permissions in code before pushing to the
    API. If overriding using @:meth:`discord.Client.event`, you must await
-   :meth:`-SlashBot.register_permissions` at the end of the event handler.
+   :meth:`SlashBot.register_permissions` at the end of the event handler.
    See ``/stop`` in ``demo_bot.py`` for an example.
 
 .. function:: on_before_slash_command_invoke(ctx: Context)
@@ -93,4 +121,17 @@ Events
 .. function:: on_after_slash_command_invoke(ctx: Context)
 
    Triggered immediately after a *successful* slash command invocation.
-   Failed invocations will trigger :func:`discord.on_command_error` instead.
+   Failed invocations will trigger :func:`discord.on_command_error` instead.
+
+.. function:: on_before_component_callback_invoke(ctx: ComponentContext)
+
+   Triggered immediately before a message component callback is invoked.
+
+.. function:: on_after_component_callback_invoke(ctx: ComponentContext)
+
+   Triggered immediately after a successful callback invocation.
+
+.. function:: on_component_callback_deregister(callback: ComponentCallback)
+
+   Triggered when a component callback is deregistered, either automatically
+   as part of TTL expiry / use counting or manually.

setup.py

@@ -9,7 +9,7 @@
 longdesc = match('^([\'"])\\1{2}(.*?)\\1{3}', contents, S).group(2)
 version = match(r'[\s\S]*__version__[^\'"]+[\'"]([^\'"]+)[\'"]', contents).group(1)
 del contents
-longdesc = sub(':class:`~?([^`]+)`', r'``\1``', longdesc)
+longdesc = sub(':(?:class|attr):`~?([^`]+)`', r'``\1``', longdesc)
 
 with open(os.path.join(os.path.dirname(__file__),
                        'README.rst'), 'w') as f2: