feat(docs): Documented some stuff

Author: mccoderpy

discord/client.py

@@ -1159,7 +1159,7 @@ def on_click(self, custom_id: Optional[Union[Pattern[AnyStr], AnyStr]] = None) -
         if so, the decorated function is called.
 
         The function this is attached to must take the same parameters as a
-        `raw_button_click-Event <https://discordpy-message-components.rtfd.io/en/latest/additions.html#on_raw_button_click>`_.
+        :func:`on_raw_button_click` event.
 
         .. important::
             The function decorated must be a coroutine, if not, :exc:`TypeError` is raised.
@@ -1226,7 +1226,7 @@ def on_select(self, custom_id: Optional[Union[Pattern[AnyStr], AnyStr]] = None)
         A decorator with which you can assign a function to a specific :class:`~discord.SelectMenu` (or its custom_id).
 
         The function this is attached to must take the same parameters as a
-        `raw_selection_select-Event <https://discordpy-message-components.rtfd.io/en/latest/additions.html#on_raw_selection_select>`_.
+        :func:`on_raw_selection_select` event.
 
         .. important::
             The decorated function must be a coroutine, if not, :exc:`TypeError` is raised.
@@ -1284,11 +1284,11 @@ def on_submit(self, custom_id: Optional[Union[Pattern[AnyStr], AnyStr]] = None)
         [Awaitable[Any]], Awaitable[Any]
     ]:
         """
-        A decorator that registers an on_modal_submit event that checks on execution if the ``custom_id's`` are the same;
+        A decorator that registers an :func:`on_modal_submit` event that checks on execution if the ``custom_id's`` are the same;
         if so, the decorated function is called.
 
         The function this is attached to must take the same parameters as a
-        `raw_button_click-Event <https://discordpy-message-components.rtfd.io/en/latest/addition.html#on_modal_submit>`_.
+        :func`on_modal_submit` event.
 
         .. important::
             The decorated function must be a coroutine, if not, :exc:`TypeError` is raised.

discord/ext/commands/bot.py

@@ -432,7 +432,7 @@ def add_interaction_listener(self, _type,  func, custom_id: re.Pattern):
         This adds an interaction(decorator) like :meth:`on_click` or :meth:`on_select` to the client listeners.
 
         .. note::
-            This should not use manuel; only cogs use this to register them.
+            This should not use directly; only cogs use this to register them.
 
         """
         try:
@@ -450,7 +450,7 @@ def remove_interaction_listener(self, _type,  func, custom_id: re.Pattern):
         This removes an interaction(decorator) like :meth:`on_click` or :meth:`on_select` from the client listeners.
 
         .. note::
-            This should not use manuel; only cogs use this to remove them.
+            This should not use directly; only cogs use this to remove them.
             
         """
         try:

discord/ext/commands/cog.py

@@ -343,7 +343,7 @@ def on_click(cls, custom_id: Optional[Union[Pattern[AnyStr], AnyStr]] = None) ->
         if so, the :func:`func` is called.
 
         The function this is attached to must take the same parameters as a
-        `raw_button_click-Event <https://discordpy-message-components.rtfd.io/en/latest/additions.html#on_raw_button_click>`_.
+        :func:`on_raw_button_click` event.
 
         .. important::
             The func must be a coroutine, if not, :exc:`TypeError` is raised.
@@ -399,7 +399,7 @@ def on_select(cls, custom_id: Optional[Union[Pattern[AnyStr], AnyStr]] = None) -
         A decorator with which you can assign a function to a specific :class:`SelectMenu` (or its custom_id).
 
         The function this is attached to must take the same parameters as a
-        `raw_selection_select-Event <https://discordpy-message-components.rtfd.io/en/latest/additions.html#on_raw_selection_select>`_.
+        :func:`on_raw_selection_select` event.
 
         .. important::
             The func must be a coroutine, if not, :exc:`TypeError` is raised.
@@ -456,11 +456,11 @@ def on_submit(self, custom_id: Optional[Union[Pattern[AnyStr], AnyStr]] = None)
         [Awaitable[Any]], Awaitable[Any]
     ]:
         """
-        A decorator that registers an on_modal_submit event that checks on execution if the ``custom_id's`` are the same;
+        A decorator that registers an :attr:`on_modal_submit` event that checks on execution if the ``custom_id's`` are the same;
          if so, the :func:`func` is called.
 
         The function this is attached to must take the same parameters as a
-        `raw_button_click-Event <https://discordpy-message-components.rtfd.io/en/latest/additions.html#on_modal_submit>`_.
+        :func:`on_modal_submit`.
 
         .. important::
             The func must be a coroutine, if not, :exc:`TypeError` is raised.

discord/interactions.py

@@ -755,7 +755,7 @@ def channel(self) -> Union[DMChannel, TextChannel, ThreadChannel, VoiceChannel]:
         """
         The channel where the interaction was invoked in.
 
-        :returns: Union[:class:`~discord.TextChannel`, :class:`~discord.ThreadChannel`, :class:`~discord.DMChannel`, :class`~discord.VoiceChannel`]
+        :returns: Union[:class:`~discord.TextChannel`, :class:`~discord.ThreadChannel`, :class:`~discord.DMChannel`, :class:`~discord.VoiceChannel`]
         """
         return getattr(self, '_channel', self.guild.get_channel(self.channel_id)
         if self.guild_id else self._state.get_channel(self.channel_id))
@@ -781,7 +781,7 @@ def message_is_hidden(self) -> bool:
 
     @property
     def bot(self):
-        """Union[:class:`~discord.Client`/:class:`~discord.ext.commands.Bot`]: The :class:`~discord.Client`/:class:`~discord.ext.commands.Bot` instance of the bot."""
+        """Union[:class:`~discord.Client`, :class:`~discord.ext.commands.Bot`]: The :class:`~discord.Client`/:class:`~discord.ext.commands.Bot` instance of the bot."""
         return self._state._get_client()
 
     @classmethod
@@ -798,6 +798,9 @@ def from_type(cls, state, data):
 
 
 class ApplicationCommandInteraction(BaseInteraction):
+    """
+    Represents the data of an interaction that will be received when a :class:`discord.SlashCommand`, :class:`discord.UserCommand` or :class:`discord.MessageCommand` is used.
+    """
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
         if self.data.type.user:
@@ -834,8 +837,12 @@ async def defer(self, hidden: bool = False) -> Union[Message, EphemeralMessage]:
 
 
 class ComponentInteraction(BaseInteraction):
+    """
+    Represents the data of an interaction which will be received when a :class:`~discord.SelectMenu` or :class:`~discord.Button` is used.
+    """
     @property
     def component(self) -> Union[Button, SelectMenu]:
+        """Union[:class:`~discord.Button`, :class:`~discord.SelectMenu`]: The component that was used"""
         if self._component is None:
             custom_id = self.data.custom_id
             if custom_id:
@@ -864,18 +871,21 @@ async def defer(self,
             Weather only the author of the command should see this, default :obj:`True`
 
              .. note::
-                Only for :class:`~discord.InteractionCallbackType.deferred_msg_with_source` (``5``).
+                Only for :attr:`~discord.InteractionCallbackType.deferred_msg_with_source` (``5``).
 
         Returns
         -------
         Optional[Union[:class:`~discord.Message, :class:`~discord.EphemeralMessage`]]:
-            The message containing the loading-state if `class`~discord.InteractionCallbackType.deferred_msg_with_source` (``5``) is used, else :obj:`None`.
+            The message containing the loading-state if :class:`~discord.InteractionCallbackType.deferred_msg_with_source` (``5``) is used, else :obj:`None`.
         """
         data = await super()._defer(type, hidden)
         return data
 
 
 class AutocompleteInteraction(BaseInteraction):
+    """
+    Represents the data of an interaction that will be received when autocomplete for a :class:`discord.SlashCommandOption` with :attr:`~discord.SlashCommandOption.autocomplete` set to :obj:`True`.
+    """
     @property
     def focused_option(self) -> 'InteractionDataOption':
         """:class:`~discord.InteractionDataOption`: Returns the currently focused option."""
@@ -916,7 +926,7 @@ async def send_choices(self, choices: List[SlashCommandOptionChoice]) -> None:
 
     @utils.copy_doc(send_choices)
     async def suggest(self, choices: List[SlashCommandOptionChoice]) -> None:
-        """An aliase for :meth:`send_choices`"""
+        """An aliase for :meth:`.send_choices`"""
         return await self.send_choices(choices)
 
     async def respond(self, *args, **kwargs):
@@ -927,6 +937,9 @@ async def defer(self, *args, **kwargs):
 
 
 class ModalSubmitInteraction(BaseInteraction):
+    """
+    Represents the data of an interaction that will be received when the ``Submit`` button of a :class:`~discord.Modal` is pressed.
+    """
     def get_field(self, custom_id) -> Union['TextInput', None]:
         """Optional[:class:`~discord.TextInput`]: Returns the field witch :attr:`~discord.TextInput.custom_id` match or :class:`None`"""
         for ar in self.data.components:

docs/api.rst

@@ -944,6 +944,64 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     :param payload: The payload containing all the information
     :type payload: :class:`AutoModActionPayload`
 
+.. function:: on_button_click(interaction, button)
+
+    Called when a :class:`Button`, that is attached to a :class:`Message` **wich is in the internal cache**, is pressed.
+
+    .. note::
+        In general it is more efficient to use :func:`~Client.on_click`/:func:`ext.commands.Cog.on_click` instead of this and :func:`on_raw_button_click` to make a callback for buttons
+
+    :param interaction: The Interaction-object with all his attributes and methods to respond to the interaction
+    :type interaction: :class:`~discord.ComponentInteraction`
+    :param button: The button that was pressed. (this is also available under :attr:`discord.ComponentInteraction.component`).
+    :type button: :class:`Button`
+
+.. function:: on_raw_button_click(interaction, button)
+
+    Called when a :class:`Button`, that is attached to **any** :class:`Message` of the bot, is pressed.
+
+    .. warning::
+        This may be removed and be included in :func:`on_button_click` in a future release
+
+    :param interaction: The Interaction-object with all his attributes and methods to respond to the interaction
+    :type interaction: :class:`~discord.ComponentInteraction`
+    :param button: The button that was pressed. (this is also available under :attr:`discord.ComponentInteraction.component`).
+    :type button: :class:`Button`
+
+.. function:: on_selection_select(interaction, select_menu)
+
+    Called when a :class:`SelectMenu`, that is attached to a :class:`Message` **wich is in the internal cache**, is used.
+
+    .. note::
+        In general it is more efficient to use :func:`~Client.on_select`/:func:`ext.commands.Cog.on_select` instead of this and :func:`on_raw_selection_select` to make a callback for select menus
+
+    :param interaction: The Interaction-object with all his attributes and methods to respond to the interaction
+    :type interaction: :class:`~discord.ComponentInteraction`
+    :param select_menu: The :class:`SelectMenu` but with the :attr:`SelectMenu.values` set wich contains a list of the selected :attr:`~SelectMenu.options`. (this is also available under :attr:`discord.ComponentInteraction.component`).
+    :type select_menu: :class:`SelectMenu`
+
+.. function:: on_raw_selection_select(interaction, select_menu)
+
+    Called when a :class:`SelectMenu`, that is attached to **any** :class:`Message` of the bot, is used.
+
+    .. warning::
+        This may be removed and be included in :func:`on_selection_select` in a future release
+
+    :param interaction: The Interaction-object with all his attributes and methods to respond to the interaction
+    :type interaction: :class:`~discord.ComponentInteraction`
+    :param select_menu: The :class:`SelectMenu` but with the :attr:`SelectMenu.values` set wich contains a list of the selected :attr:`~SelectMenu.options`. (this is also available under :attr:`discord.ComponentInteraction.component`).
+    :type select_menu: :class:`SelectMenu`
+
+.. function:: on_modal_submit(interaction)
+
+    Called when a user press the ``Submit`` button in a :class:`Modal`.
+
+    .. note::
+        In general it is more efficient to use :func:`~Client.on_submit`/:func:`ext.commands.Cog.on_submit` instead of this to make a callback for modals
+
+    :param interaction: he Interaction-object with all his attributes and methods to respond to the interaction
+    :type interaction: :class:`~discord.ModalSubmitInteraction`
+
 .. _discord-api-utils:
 
 Utility Functions

docs/conf.py

@@ -21,7 +21,6 @@
 
 sys.setrecursionlimit(15000)
 
-
 sys.path.insert(0, os.path.abspath('..'))
 sys.path.append(os.path.abspath('extensions'))
 
@@ -57,6 +56,7 @@
     'sphinx.ext.intersphinx',
     'sphinxcontrib.contentui',
     'sphinx.ext.napoleon',
+    'sphinxext.opengraph',
     'sphinxcontrib_trio',
     'details',
     'exception_hierarchy',

docs/index.rst

@@ -47,7 +47,7 @@
    :target: https://pypi.org
 
 .. centered::
-   **Visit on** |PyPI| **PyPI** `here <https://pypi.org/project/discord.py-message-components>`_
+    **Visit on** |PyPI| **PyPI** `here <https://pypi.org/project/discord.py-message-components>`_
 
 
 discord.py-message-components is a modern, easy to use, feature-rich, and async ready API wrapper

docs/requirements.txt

@@ -1,5 +1,6 @@
 sphinxcontrib_trio
 sphinxcontrib-contentui==0.2.5
+sphinxext-opengraph
 Jinja2 >.0.3
 Pigments
 typing-extensions