Add missing docs

discord/enums.py

@@ -607,7 +607,7 @@ class ApplicationType(Enum):
 
 
 class StagePrivacyLevel(Enum):
-    public = 1
+    # public = 1 Deprecated
     closed = 2
     guild_only = 2
 

docs/api.rst

@@ -1381,6 +1381,10 @@ of :class:`enum.Enum`.
 
         A floating number.
 
+    .. attribute:: attachment
+
+        An attachment. Currently in beta.
+
 .. class:: ChannelType
 
     Specifies the type of channel.
@@ -2613,18 +2617,60 @@ of :class:`enum.Enum`.
 
         A scheduled event was created.
 
+        When this is the action, the type of :attr:`~AuditLogEntry.target` is
+        the :class:`ScheduledEvent` or :class:`Object` with the ID of the thread which
+        was deleted.
+
+        Possible attributes for :class:`AuditLogDiff`:
+
+        - :attr:`~AuditLogDiff.name`
+        - :attr:`~AuditLogDiff.description`
+        - :attr:`~AuditLogDiff.channel`
+        - :attr:`~AuditLogDiff.privacy_level`
+        - :attr:`~AuditLogDiff.location`
+        - :attr:`~AuditLogDiff.status`
+        - :attr:`~AuditLogDiff.location_type`
+
         .. versionadded:: 2.0
 
     .. attribute:: scheduled_event_update
 
         A scheduled event was updated.
 
+        When this is the action, the type of :attr:`~AuditLogEntry.target` is
+        the :class:`ScheduledEvent` or :class:`Object` with the ID of the thread which
+        was deleted.
+
+        Possible attributes for :class:`AuditLogDiff`:
+
+        - :attr:`~AuditLogDiff.name`
+        - :attr:`~AuditLogDiff.description`
+        - :attr:`~AuditLogDiff.channel`
+        - :attr:`~AuditLogDiff.privacy_level`
+        - :attr:`~AuditLogDiff.location`
+        - :attr:`~AuditLogDiff.status`
+        - :attr:`~AuditLogDiff.location_type`
+
         .. versionadded:: 2.0
 
     .. attribute:: scheduled_event_delete
 
         A scheduled event was deleted.
 
+        When this is the action, the type of :attr:`~AuditLogEntry.target` is
+        the :class:`ScheduledEvent` or :class:`Object` with the ID of the thread which
+        was deleted.
+
+        Possible attributes for :class:`AuditLogDiff`:
+
+        - :attr:`~AuditLogDiff.name`
+        - :attr:`~AuditLogDiff.description`
+        - :attr:`~AuditLogDiff.channel`
+        - :attr:`~AuditLogDiff.privacy_level`
+        - :attr:`~AuditLogDiff.location`
+        - :attr:`~AuditLogDiff.status`
+        - :attr:`~AuditLogDiff.location_type`
+
         .. versionadded:: 2.0
 
     .. attribute:: thread_create
@@ -2641,6 +2687,7 @@ of :class:`enum.Enum`.
         - :attr:`~AuditLogDiff.archived`
         - :attr:`~AuditLogDiff.locked`
         - :attr:`~AuditLogDiff.auto_archive_duration`
+        - :attr:`~AuditLogDiff.invitable`
 
         .. versionadded:: 2.0
 
@@ -2658,6 +2705,7 @@ of :class:`enum.Enum`.
         - :attr:`~AuditLogDiff.archived`
         - :attr:`~AuditLogDiff.locked`
         - :attr:`~AuditLogDiff.auto_archive_duration`
+        - :attr:`~AuditLogDiff.invitable`
 
         .. versionadded:: 2.0
 
@@ -2675,6 +2723,7 @@ of :class:`enum.Enum`.
         - :attr:`~AuditLogDiff.archived`
         - :attr:`~AuditLogDiff.locked`
         - :attr:`~AuditLogDiff.auto_archive_duration`
+        - :attr:`~AuditLogDiff.invitable`
 
         .. versionadded:: 2.0
 
@@ -2845,13 +2894,11 @@ of :class:`enum.Enum`.
 .. class:: StagePrivacyLevel
 
     Represents a stage instance's privacy level.
+    Stage event privacy levels can only have 1 possible value at the moment so
+    this shouldn't really be used.
 
     .. versionadded:: 2.0
 
-    .. attribute:: public
-
-        The stage instance can be joined by external users.
-
     .. attribute:: closed
 
         The stage instance can only be joined by members of the guild.
@@ -2907,6 +2954,14 @@ of :class:`enum.Enum`.
 
     Represents an embedded activity application.
 
+    Some might be boost-only or gated.
+
+    .. warning::
+
+        Discord said that they won't verify bots who gives access to embedded activities.
+
+        Read more here: https://discord.com/channels/613425648685547541/697236247739105340/901153332075315321.
+
     .. versionadded:: 2.0
 
     .. attribute:: awkword
@@ -3496,9 +3551,9 @@ AuditLogDiff
 
     .. attribute:: privacy_level
 
-        The privacy level of the stage instance.
+        The privacy level of the stage instance or scheduled event.
 
-        :type: :class:`StagePrivacyLevel`
+        :type: :class:`StagePrivacyLevel` or :class:`ScheduledEventPrivacyLevel`
 
     .. attribute:: roles
 

docs/cogs.rst

@@ -0,0 +1,97 @@
+:orphan:
+
+.. currentmodule:: discord
+.. _cogs:
+
+Cogs
+======
+
+There comes a point in your bot's development when you want to organize a collection of commands, listeners, and some state into one class. Cogs allow you to do just that.
+
+The gist:
+
+- Each cog is a Python class that subclasses :class:`.Cog`.
+- Every command is marked with the :func:`.command` decorator or the corresponding shortcut command decorator.
+- Every listener is marked with the :meth:`.Cog.listener` decorator.
+- Cogs are then registered with the :meth:`.Bot.add_cog` call.
+- Cogs are subsequently removed with the :meth:`.Bot.remove_cog` call.
+
+Quick Example
+---------------
+
+This example cog defines a ``Greetings`` category for your commands, with a single slash command named ``hello`` as well as a listener to listen to an :ref:`Event <discord-api-events>`.
+
+.. code-block:: python3
+
+    class Greetings(discord.Cog):
+        def __init__(self, bot):
+            self.bot = bot
+            self._last_member = None
+
+        @discord.Cog.listener()
+        async def on_member_join(self, member):
+            channel = member.guild.system_channel
+            if channel is not None:
+                await channel.send(f'Welcome {member.mention}.')
+
+        @discord.slash_command()
+        async def hello(self, ctx, *, member: discord.Member = None):
+            """Says hello"""
+            member = member or ctx.author
+            if self._last_member is None or self._last_member.id != member.id:
+                await ctx.send(f'Hello {member.name}~')
+            else:
+                await ctx.send(f'Hello {member.name}... This feels familiar.')
+            self._last_member = member
+
+A couple of technical notes to take into consideration:
+
+- All listeners must be explicitly marked via decorator, :meth:`~.Cog.listener`.
+- The name of the cog is automatically derived from the class name but can be overridden.
+- All commands must now take a ``self`` parameter to allow usage of instance attributes that can be used to maintain state.
+
+Cog Registration
+-------------------
+
+Once you have defined your cogs, you need to tell the bot to register the cogs to be used. We do this via the :meth:`~.Bot.add_cog` method.
+
+.. code-block:: python3
+
+    bot.add_cog(Greetings(bot))
+
+This binds the cog to the bot, adding all commands and listeners to the bot automatically.
+
+Using Cogs
+-------------
+
+Just as we remove a cog by its name, we can also retrieve it by its name as well. This allows us to use a cog as an inter-command communication protocol to share data. For example:
+
+.. code-block:: python3
+    :emphasize-lines: 22,24
+
+    class Economy(discord.Cog):
+        ...
+
+        async def withdraw_money(self, member, money):
+            # implementation here
+            ...
+
+        async def deposit_money(self, member, money):
+            # implementation here
+            ...
+
+    class Gambling(discord.Cog):
+        def __init__(self, bot):
+            self.bot = bot
+
+        def coinflip(self):
+            return random.randint(0, 1)
+
+        @discord.slash_command()
+        async def gamble(self, ctx, money: int):
+            """Gambles some money."""
+            economy = self.bot.get_cog('Economy')
+            if economy is not None:
+                await economy.withdraw_money(ctx.author, money)
+                if self.coinflip() == 1:
+                    await economy.deposit_money(ctx.author, money * 1.5)