Docs Refactor

docs/api/abcs.rst

@@ -0,0 +1,65 @@
+.. _discord_api_abcs:
+
+Abstract Base Classes
+=====================
+
+An :term:`abstract base class` (also known as an ``abc``) is a class that models can inherit
+to get their behaviour. **Abstract base classes should not be instantiated**.
+They are mainly there for usage with :func:`isinstance` and :func:`issubclass`\.
+
+This library has a module related to abstract base classes, in which all the ABCs are subclasses of
+:class:`typing.Protocol`.
+
+Snowflake
+---------
+
+.. attributetable:: discord.abc.Snowflake
+
+.. autoclass:: discord.abc.Snowflake()
+    :members:
+
+User
+----
+
+.. attributetable:: discord.abc.User
+
+.. autoclass:: discord.abc.User()
+    :members:
+
+PrivateChannel
+--------------
+
+.. attributetable:: discord.abc.PrivateChannel
+
+.. autoclass:: discord.abc.PrivateChannel()
+    :members:
+
+GuildChannel
+------------
+
+.. attributetable:: discord.abc.GuildChannel
+
+.. autoclass:: discord.abc.GuildChannel()
+    :members:
+
+Messageable
+-----------
+
+.. attributetable:: discord.abc.Messageable
+
+.. autoclass:: discord.abc.Messageable()
+    :members:
+    :exclude-members: history, typing
+
+    .. automethod:: discord.abc.Messageable.history
+        :async-for:
+
+    .. automethod:: discord.abc.Messageable.typing
+        :async-with:
+
+Connectable
+-----------
+
+.. attributetable:: discord.abc.Connectable
+
+.. autoclass:: discord.abc.Connectable()

docs/api/application_commands.rst

@@ -0,0 +1,114 @@
+.. currentmodule:: discord
+
+Application Commands
+====================
+
+
+Command Permission Decorators
+-----------------------------
+
+
+.. autofunction:: discord.commands.default_permissions
+    :decorator:
+
+.. autofunction:: discord.commands.guild_only
+    :decorator:
+
+
+ApplicationCommand
+------------------
+
+.. attributetable:: ApplicationCommand
+
+.. autoclass:: ApplicationCommand
+    :members:
+
+.. autofunction:: discord.commands.application_command
+    :decorator:
+
+.. autofunction:: discord.commands.command
+    :decorator:
+
+SlashCommand
+------------
+
+.. attributetable:: SlashCommand
+
+.. autoclass:: SlashCommand
+    :members:
+
+.. autofunction:: discord.commands.slash_command
+    :decorator:
+
+SlashCommandGroup
+-----------------
+
+.. attributetable:: SlashCommandGroup
+
+.. autoclass:: SlashCommandGroup
+    :members:
+
+Option
+------
+
+.. attributetable:: Option
+
+.. autoclass:: Option
+    :members:
+
+.. autofunction:: discord.commands.option
+    :decorator:
+
+ThreadOption
+------------
+
+.. attributetable:: ThreadOption
+
+.. autoclass:: ThreadOption
+    :members:
+
+OptionChoice
+------------
+
+.. attributetable:: OptionChoice
+
+.. autoclass:: OptionChoice
+    :members:
+
+UserCommand
+-----------
+
+.. attributetable:: UserCommand
+
+.. autoclass:: UserCommand
+    :members:
+
+.. autofunction:: discord.commands.user_command
+    :decorator:
+
+MessageCommand
+--------------
+
+.. attributetable:: MessageCommand
+
+.. autoclass:: MessageCommand
+    :members:
+
+.. autofunction:: discord.commands.message_command
+    :decorator:
+
+ApplicationContext
+------------------
+
+.. attributetable:: ApplicationContext
+
+.. autoclass:: ApplicationContext
+    :members:
+
+AutocompleteContext
+-------------------
+
+.. attributetable:: AutocompleteContext
+
+.. autoclass:: AutocompleteContext
+    :members:

docs/api/application_info.rst

@@ -0,0 +1,36 @@
+.. currentmodule:: discord
+
+Application Info
+================
+
+AppInfo
+-------
+
+.. attributetable:: AppInfo
+
+.. autoclass:: AppInfo()
+    :members:
+
+PartialAppInfo
+--------------
+
+.. attributetable:: PartialAppInfo
+
+.. autoclass:: PartialAppInfo()
+    :members:
+
+Team
+----
+
+.. attributetable:: Team
+
+.. autoclass:: Team()
+    :members:
+
+TeamMember
+----------
+
+.. attributetable:: TeamMember
+
+.. autoclass:: TeamMember()
+    :members:

docs/api/async_iter.rst

@@ -0,0 +1,130 @@
+.. currentmodule:: discord
+
+Async Iterator
+==============
+
+Some API functions return an "async iterator". An async iterator is something that is
+capable of being used in an :ref:`async for statement <py:async for>`.
+
+These async iterators can be used as follows: ::
+
+    async for elem in channel.history():
+        # do stuff with elem here
+
+Certain utilities make working with async iterators easier, detailed below.
+
+.. class:: AsyncIterator
+
+    Represents the "AsyncIterator" concept. Note that no such class exists,
+    it is purely abstract.
+
+    .. container:: operations
+
+        .. describe:: async for x in y
+
+            Iterates over the contents of the async iterator.
+
+
+    .. method:: next()
+        :async:
+
+        |coro|
+
+        Advances the iterator by one, if possible. If no more items are found
+        then this raises :exc:`NoMoreItems`.
+
+    .. method:: get(**attrs)
+        :async:
+
+        |coro|
+
+        Similar to :func:`utils.get` except run over the async iterator.
+
+        Getting the last message by a user named 'Dave' or ``None``: ::
+
+            msg = await channel.history().get(author__name='Dave')
+
+    .. method:: find(predicate)
+        :async:
+
+        |coro|
+
+        Similar to :func:`utils.find` except run over the async iterator.
+
+        Unlike :func:`utils.find`\, the predicate provided can be a
+        |coroutine_link|_.
+
+        Getting the last audit log with a reason or ``None``: ::
+
+            def predicate(event):
+                return event.reason is not None
+
+            event = await guild.audit_logs().find(predicate)
+
+        :param predicate: The predicate to use. Could be a |coroutine_link|_.
+        :return: The first element that returns ``True`` for the predicate or ``None``.
+
+    .. method:: flatten()
+        :async:
+
+        |coro|
+
+        Flattens the async iterator into a :class:`list` with all the elements.
+
+        :return: A list of every element in the async iterator.
+        :rtype: list
+
+    .. method:: chunk(max_size)
+
+        Collects items into chunks of up to a given maximum size.
+        Another :class:`AsyncIterator` is returned which collects items into
+        :class:`list`\s of a given size. The maximum chunk size must be a positive integer.
+
+        .. versionadded:: 1.6
+
+        Collecting groups of users: ::
+
+            async for leader, *users in reaction.users().chunk(3):
+                ...
+
+        .. warning::
+
+            The last chunk collected may not be as large as ``max_size``.
+
+        :param max_size: The size of individual chunks.
+        :rtype: :class:`AsyncIterator`
+
+    .. method:: map(func)
+
+        This is similar to the built-in :func:`map <py:map>` function. Another
+        :class:`AsyncIterator` is returned that executes the function on
+        every element it is iterating over. This function can either be a
+        regular function or a |coroutine_link|_.
+
+        Creating a content iterator: ::
+
+            def transform(message):
+                return message.content
+
+            async for content in channel.history().map(transform):
+                message_length = len(content)
+
+        :param func: The function to call on every element. Could be a |coroutine_link|_.
+        :rtype: :class:`AsyncIterator`
+
+    .. method:: filter(predicate)
+
+        This is similar to the built-in :func:`filter <py:filter>` function. Another
+        :class:`AsyncIterator` is returned that filters over the original
+        async iterator. This predicate can be a regular function or a |coroutine_link|_.
+
+        Getting messages by non-bot accounts: ::
+
+            def predicate(message):
+                return not message.author.bot
+
+            async for elem in channel.history().filter(predicate):
+                ...
+
+        :param predicate: The predicate to call on every element. Could be a |coroutine_link|_.
+        :rtype: :class:`AsyncIterator`