Organise documentation

.github/CONTRIBUTING.md

@@ -20,7 +20,7 @@ Please try your best not to ask questions in our issue tracker. Most of them don
 Please be aware of the following things when filing bug reports.
 
 1. Don't open duplicate issues. Please search your issue to see if it has been asked already. Duplicate issues will be closed.
-2. When filing a bug about exceptions or tracebacks, please include the *complete* traceback. Without the complete traceback the issue might be **unsolveable** and you will be asked to provide more information.
+2. When filing a bug about exceptions or tracebacks, please include the *complete* traceback. Without the complete traceback the issue might be **unsolvable** and you will be asked to provide more information.
 3. Make sure to provide enough information to make the issue workable. The issue template will generally walk you through the process but they are enumerated here as well:
     - A **summary** of your bug report. This is generally a quick sentence or two to describe the issue in human terms.
     - Guidance on **how to reproduce the issue**. Ideally, this should have a small code sample that allows us to run and see the issue for ourselves to debug. **Please make sure that the token is not displayed**. If you cannot provide a code snippet, then let us know what the steps were, how often it happens, etc.

discord/abc.py

@@ -304,7 +304,7 @@ class GuildChannel:
 
     @property
     def mention(self):
-        """:class:`str` : The string that allows you to mention the channel."""
+        """:class:`str`: The string that allows you to mention the channel."""
         return '<#%s>' % self.id
 
     @property
@@ -389,7 +389,7 @@ class GuildChannel:
 
         Parameters
         ----------
-        member : :class:`Member`
+        member: :class:`Member`
             The member to resolve permissions for.
 
         Returns
@@ -488,7 +488,7 @@ class GuildChannel:
 
         Parameters
         -----------
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for deleting this channel.
             Shows up on the audit log.
 
@@ -551,7 +551,7 @@ class GuildChannel:
         \*\*permissions
             A keyword argument list of permissions to set for ease of use.
             Cannot be mixed with ``overwrite``.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for doing this action. Shows up on the audit log.
 
         Raises
@@ -607,20 +607,20 @@ class GuildChannel:
 
         Parameters
         ------------
-        max_age : int
+        max_age: :class:`int`
             How long the invite should last. If it's 0 then the invite
             doesn't expire. Defaults to 0.
-        max_uses : int
+        max_uses: :class:`int`
             How many uses the invite could be used for. If it's 0 then there
             are unlimited uses. Defaults to 0.
-        temporary : bool
+        temporary: :class:`bool`
             Denotes that the invite grants temporary membership
             (i.e. they get kicked after they disconnect). Defaults to False.
-        unique: bool
+        unique: :class:`bool`
             Indicates if a unique invite URL should be created. Defaults to True.
             If this is set to False then it will return a previously created
             invite.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for creating this invite. Shows up on the audit log.
 
         Raises
@@ -710,7 +710,7 @@ class Messageable(metaclass=abc.ABCMeta):
         ------------
         content
             The content of the message to send.
-        tts: bool
+        tts: :class:`bool`
             Indicates if the message should be sent using text-to-speech.
         embed: :class:`.Embed`
             The rich embed for the content.
@@ -718,10 +718,10 @@ class Messageable(metaclass=abc.ABCMeta):
             The file to upload.
         files: List[:class:`.File`]
             A list of files to upload. Must be a maximum of 10.
-        nonce: int
+        nonce: :class:`int`
             The nonce to use for sending this message. If the message was successfully sent,
             then the message will have a nonce with this value.
-        delete_after: float
+        delete_after: :class:`float`
             If provided, the number of seconds to wait in the background
             before deleting the message we just sent. If the deletion fails,
             then it is silently ignored.
@@ -828,11 +828,6 @@ class Messageable(metaclass=abc.ABCMeta):
         id: :class:`int`
             The message ID to look for.
 
-        Returns
-        --------
-        :class:`.Message`
-            The message asked for.
-
         Raises
         --------
         :exc:`.NotFound`
@@ -841,6 +836,11 @@ class Messageable(metaclass=abc.ABCMeta):
             You do not have the permissions required to get a message.
         :exc:`.HTTPException`
             Retrieving the message failed.
+
+        Returns
+        --------
+        :class:`.Message`
+            The message asked for.
         """
 
         channel = await self._get_channel()
@@ -868,6 +868,21 @@ class Messageable(metaclass=abc.ABCMeta):
 
         You must have :attr:`~.Permissions.read_message_history` permissions to use this.
 
+        Examples
+        ---------
+
+        Usage ::
+
+            counter = 0
+            async for message in channel.history(limit=200):
+                if message.author == client.user:
+                    counter += 1
+
+        Flattening into a list: ::
+
+            messages = await channel.history(limit=123).flatten()
+            # messages is now a list of Message...
+
         All parameters are optional.
 
         Parameters
@@ -887,7 +902,7 @@ class Messageable(metaclass=abc.ABCMeta):
             If a date is provided it must be a timezone-naive datetime representing UTC time.
             When using this argument, the maximum limit is 101. Note that if the limit is an
             even number then this will return at most limit + 1 messages.
-        reverse: bool
+        reverse: Optional[:class:`bool`]
             If set to true, return messages in oldest->newest order. If unspecified,
             this defaults to ``False`` for most cases. However if passing in a
             ``after`` parameter then this is set to ``True``. This avoids getting messages
@@ -904,21 +919,6 @@ class Messageable(metaclass=abc.ABCMeta):
         -------
         :class:`.Message`
             The message with the message data parsed.
-
-        Examples
-        ---------
-
-        Usage ::
-
-            counter = 0
-            async for message in channel.history(limit=200):
-                if message.author == client.user:
-                    counter += 1
-
-        Flattening into a list: ::
-
-            messages = await channel.history(limit=123).flatten()
-            # messages is now a list of Message...
         """
         return HistoryIterator(self, limit=limit, before=before, after=after, around=around, reverse=reverse)
 
@@ -949,9 +949,9 @@ class Connectable(metaclass=abc.ABCMeta):
 
         Parameters
         -----------
-        timeout: float
+        timeout: :class:`float`
             The timeout in seconds to wait for the voice endpoint.
-        reconnect: bool
+        reconnect: :class:`bool`
             Whether the bot should automatically attempt
             a reconnect if a part of the handshake fails
             or the gateway goes down.

discord/backoff.py

@@ -41,10 +41,10 @@ class ExponentialBackoff:
 
     Parameters
     ----------
-    base: int
+    base: :class:`int`
         The base delay in seconds.  The first retry-delay will be up to
         this many seconds.
-    integral: bool
+    integral: :class:`bool`
         Set to True if whole periods of base is desirable, otherwise any
         number in between may be returned.
     """

discord/calls.py

@@ -53,7 +53,7 @@ class CallMessage:
 
     @property
     def call_ended(self):
-        """:obj:`bool`: Indicates if the call has ended."""
+        """:class:`bool`: Indicates if the call has ended."""
         return self.ended_timestamp is not None
 
     @property
@@ -87,7 +87,7 @@ class GroupCall:
     -----------
     call: :class:`CallMessage`
         The call message associated with this group call.
-    unavailable: :obj:`bool`
+    unavailable: :class:`bool`
         Denotes if this group call is unavailable.
     ringing: List[:class:`User`]
         A list of users that are currently being rung to join the call.
@@ -122,7 +122,7 @@ class GroupCall:
 
     @property
     def connected(self):
-        """A property that returns the :obj:`list` of :class:`User` that are currently in this call."""
+        """A property that returns the :class:`list` of :class:`User` that are currently in this call."""
         ret = [u for u in self.channel.recipients if self.voice_state_for(u) is not None]
         me = self.channel.me
         if self.voice_state_for(me) is not None:

discord/channel.py

@@ -255,9 +255,20 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
         on the conditions met such as if a bulk delete is possible or if
         the account is a user bot or not.
 
+        Examples
+        ---------
+
+        Deleting bot's messages ::
+
+            def is_me(m):
+                return m.author == client.user
+
+            deleted = await channel.purge(limit=100, check=is_me)
+            await channel.send('Deleted {} message(s)'.format(len(deleted)))
+
         Parameters
         -----------
-        limit: Optional[int]
+        limit: Optional[:class:`int`]
             The number of messages to search through. This is not the number
             of messages that will be deleted, though it can be.
         check: predicate
@@ -271,7 +282,7 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
             Same as ``around`` in :meth:`history`.
         reverse
             Same as ``reverse`` in :meth:`history`.
-        bulk: bool
+        bulk: class:`bool`
             If True, use bulk delete. bulk=False is useful for mass-deleting
             a bot's own messages without manage_messages. When True, will fall
             back to single delete if current account is a user bot, or if
@@ -284,20 +295,9 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
         HTTPException
             Purging the messages failed.
 
-        Examples
-        ---------
-
-        Deleting bot's messages ::
-
-            def is_me(m):
-                return m.author == client.user
-
-            deleted = await channel.purge(limit=100, check=is_me)
-            await channel.send('Deleted {} message(s)'.format(len(deleted)))
-
         Returns
         --------
-        list
+        List[:class:`.Message`]
             The list of messages that were deleted.
         """
 
@@ -378,9 +378,9 @@ class TextChannel(discord.abc.Messageable, discord.abc.GuildChannel, Hashable):
 
         Parameters
         -------------
-        name: str
+        name: :class:`str`
             The webhook's name.
-        avatar: Optional[bytes]
+        avatar: Optional[:class:`bytes`]
             A :term:`py:bytes-like object` representing the webhook's default avatar.
             This operates similarly to :meth:`~ClientUser.edit`.
 
@@ -507,21 +507,21 @@ class VoiceChannel(discord.abc.Connectable, discord.abc.GuildChannel, Hashable):
 
         Parameters
         ----------
-        name: str
+        name: :class:`str`
             The new channel's name.
-        bitrate: int
+        bitrate: :class:`int`
             The new channel's bitrate.
-        user_limit: int
+        user_limit: :class:`int`
             The new channel's user limit.
-        position: int
+        position: :class:`int`
             The new channel's position.
-        sync_permissions: bool
+        sync_permissions: :class:`bool`
             Whether to sync permissions with the channel's new or pre-existing
             category. Defaults to ``False``.
         category: Optional[:class:`CategoryChannel`]
             The new category for this channel. Can be ``None`` to remove the
             category.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for editing this channel. Shows up on the audit log.
 
         Raises
@@ -607,13 +607,13 @@ class CategoryChannel(discord.abc.GuildChannel, Hashable):
 
         Parameters
         ----------
-        name: str
+        name: :class:`str`
             The new category's name.
-        position: int
+        position: :class:`int`
             The new category's position.
-        nsfw: bool
+        nsfw: :class:`bool`
             To mark the category as NSFW or not.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for editing this category. Shows up on the audit log.
 
         Raises
@@ -1053,10 +1053,10 @@ class GroupChannel(discord.abc.Messageable, Hashable):
 
         Parameters
         -----------
-        name: Optional[str]
+        name: Optional[:class:`str`]
             The new name to change the group to.
             Could be ``None`` to remove the name.
-        icon: Optional[bytes]
+        icon: Optional[:class:`bytes`]
             A :term:`py:bytes-like object` representing the new icon.
             Could be ``None`` to remove the icon.
 

discord/client.py

@@ -76,22 +76,22 @@ class Client:
 
     Parameters
     -----------
-    max_messages : Optional[:class:`int`]
+    max_messages: Optional[:class:`int`]
         The maximum number of messages to store in the internal message cache.
         This defaults to 5000. Passing in `None` or a value less than 100
         will use the default instead of the passed in value.
-    loop : Optional[event loop]
+    loop: Optional[event loop]
         The `event loop`_ to use for asynchronous operations. Defaults to ``None``,
         in which case the default event loop is used via ``asyncio.get_event_loop()``.
-    connector : aiohttp.BaseConnector
+    connector: aiohttp.BaseConnector
         The `connector`_ to use for connection pooling.
-    proxy : Optional[:class:`str`]
+    proxy: Optional[:class:`str`]
         Proxy URL.
-    proxy_auth : Optional[aiohttp.BasicAuth]
+    proxy_auth: Optional[aiohttp.BasicAuth]
         An object that represents proxy HTTP Basic Authorization.
-    shard_id : Optional[:class:`int`]
+    shard_id: Optional[:class:`int`]
         Integer starting at 0 and less than shard_count.
-    shard_count : Optional[:class:`int`]
+    shard_count: Optional[:class:`int`]
         The total number of shards.
     fetch_offline_members: :class:`bool`
         Indicates if :func:`on_ready` should be delayed to fetch all offline
@@ -180,7 +180,7 @@ class Client:
 
     @property
     def latency(self):
-        """:obj:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
+        """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds.
 
         This could be referred to as the Discord WebSocket protocol latency.
         """
@@ -219,7 +219,7 @@ class Client:
         return self._connection.voice_clients
 
     def is_ready(self):
-        """:obj:`bool`: Specifies if the client's internal cache is ready for use."""
+        """:class:`bool`: Specifies if the client's internal cache is ready for use."""
         return self._ready.is_set()
 
     async def _run_event(self, coro, event_name, *args, **kwargs):
@@ -300,7 +300,7 @@ class Client:
 
         Parameters
         -----------
-        \*guilds
+        \*guilds: :class:`Guild`
             An argument list of guilds to request offline members for.
 
         Raises
@@ -331,10 +331,10 @@ class Client:
 
         Parameters
         -----------
-        token: str
+        token: :class:`str`
             The authentication token. Do not prefix this token with
             anything as the library will do it for you.
-        bot: bool
+        bot: :class:`bool`
             Keyword argument that specifies if the account logging on is a bot
             token or not.
 
@@ -381,7 +381,7 @@ class Client:
 
         Parameters
         -----------
-        reconnect: bool
+        reconnect: :class:`bool`
             If we should attempt reconnecting, either due to internet
             failure or a specific failure on Discord's part. Certain
             disconnects that lead to bad state will not be handled (such as
@@ -538,8 +538,8 @@ class Client:
             finally:
                 loop.close()
 
-        Warning
+        .. warning::
-        --------
+
             This function must be the last function to call due to the fact that it
             is blocking. That means that registration of events or anything being
             called after this function call will not execute until it returns.
@@ -574,7 +574,7 @@ class Client:
     # properties
 
     def is_closed(self):
-        """:obj:`bool`: Indicates if the websocket connection is closed."""
+        """:class:`bool`: Indicates if the websocket connection is closed."""
         return self._closed.is_set()
 
     @property
@@ -595,7 +595,7 @@ class Client:
 
     @property
     def users(self):
-        """Returns a :obj:`list` of all the :class:`User` the bot can see."""
+        """Returns a :class:`list` of all the :class:`User` the bot can see."""
         return list(self._connection._users.values())
 
     def get_channel(self, id):
@@ -626,8 +626,8 @@ class Client:
                 for channel in guild.channels:
                     yield channel
 
-        Note
+        .. note::
-        -----
+
             Just because you receive a :class:`abc.GuildChannel` does not mean that
             you can communicate in said channel. :meth:`abc.GuildChannel.permissions_for` should
             be used for that.
@@ -674,7 +674,7 @@ class Client:
         :exc:`asyncio.TimeoutError` for you in case of timeout and is provided for
         ease of use.
 
-        In case the event returns multiple arguments, a :obj:`tuple` containing those
+        In case the event returns multiple arguments, a :class:`tuple` containing those
         arguments is returned instead. Please check the
         :ref:`documentation <discord-api-events>` for a list of events and their
         parameters.
@@ -719,13 +719,13 @@ class Client:
 
         Parameters
         ------------
-        event: str
+        event: :class:`str`
             The event name, similar to the :ref:`event reference <discord-api-events>`,
             but without the ``on_`` prefix, to wait for.
         check: Optional[predicate]
             A predicate to check what to wait for. The arguments must meet the
             parameters of the event being waited for.
-        timeout: Optional[float]
+        timeout: Optional[:class:`float`]
             The number of seconds to wait before timing out and raising
             :exc:`asyncio.TimeoutError`.
 
@@ -737,7 +737,7 @@ class Client:
         Returns
         --------
         Any
-            Returns no arguments, a single argument, or a :obj:`tuple` of multiple
+            Returns no arguments, a single argument, or a :class:`tuple` of multiple
             arguments that mirrors the parameters passed in the
             :ref:`event reference <discord-api-events>`.
         """
@@ -770,11 +770,11 @@ class Client:
         Example
         ---------
 
-		::
+        .. code-block:: python3
+
             @client.event
             async def on_ready():
                 print('Ready!')
-
         """
 
         if not asyncio.iscoroutinefunction(coro):
@@ -793,7 +793,10 @@ class Client:
         the activity being done currently. This could also be the slimmed down versions,
         :class:`Game` and :class:`Streaming`.
 
-        Example: ::
+        Example
+        ---------
+
+        .. code-block:: python3
 
             game = discord.Game("with the API")
             await client.change_presence(status=discord.Status.idle, activity=game)
@@ -805,7 +808,7 @@ class Client:
         status: Optional[:class:`Status`]
             Indicates what status to change to. If None, then
             :attr:`Status.online` is used.
-        afk: bool
+        afk: :class:`bool`
             Indicates if you are going AFK. This allows the discord
             client to know how to handle push notifications better
             for you in case you are actually idle and not lying.
@@ -847,12 +850,12 @@ class Client:
 
         Parameters
         ----------
-        name: str
+        name: :class:`str`
             The name of the guild.
         region: :class:`VoiceRegion`
             The region for the voice communication server.
             Defaults to :attr:`VoiceRegion.us_west`.
-        icon: bytes
+        icon: :class:`bytes`
             The :term:`py:bytes-like object` representing the icon. See :meth:`~ClientUser.edit`
             for more details on what is expected.
 
@@ -887,8 +890,8 @@ class Client:
 
         Gets an :class:`Invite` from a discord.gg URL or ID.
 
-        Note
+        .. note::
-        ------
+
             If the invite is for a guild you have not joined, the guild and channel
             attributes of the returned :class:`Invite` will be :class:`PartialInviteGuild` and
             :class:`PartialInviteChannel` respectively.
@@ -929,7 +932,7 @@ class Client:
 
         Parameters
         ----------
-        invite
+        invite: Union[:class:`Invite`, :class:`str`]
             The invite to revoke.
 
         Raises
@@ -952,15 +955,15 @@ class Client:
 
         Retrieve's the bot's application information.
 
-        Returns
-        --------
-        :class:`AppInfo`
-            A namedtuple representing the application info.
-
         Raises
         -------
         HTTPException
             Retrieving the information failed somehow.
+
+        Returns
+        --------
+        :class:`AppInfo`
+            A namedtuple representing the application info.
         """
         data = await self.http.application_info()
         if 'rpc_origins' not in data:
@@ -981,20 +984,20 @@ class Client:
 
         Parameters
         -----------
-        user_id: int
+        user_id: :class:`int`
             The user's ID to fetch from.
 
-        Returns
-        --------
-        :class:`User`
-            The user you requested.
-
         Raises
         -------
         NotFound
             A user with this ID does not exist.
         HTTPException
             Fetching the user failed.
+
+        Returns
+        --------
+        :class:`User`
+            The user you requested.
         """
         data = await self.http.get_user_info(user_id)
         return User(state=self._connection, data=data)
@@ -1006,7 +1009,7 @@ class Client:
 
         Parameters
         ------------
-        user_id: int
+        user_id: :class:`int`
             The ID of the user to fetch their profile for.
 
         Raises

discord/embeds.py

@@ -238,9 +238,9 @@ class Embed:
 
         Parameters
         -----------
-        text: str
+        text: :class:`str`
             The footer text.
-        icon_url: str
+        icon_url: :class:`str`
             The URL of the footer icon. Only HTTP(S) is supported.
         """
 
@@ -276,7 +276,7 @@ class Embed:
 
         Parameters
         -----------
-        url: str
+        url: :class:`str`
             The source URL for the image. Only HTTP(S) is supported.
         """
 
@@ -309,7 +309,7 @@ class Embed:
 
         Parameters
         -----------
-        url: str
+        url: :class:`str`
             The source URL for the thumbnail. Only HTTP(S) is supported.
         """
 
@@ -361,11 +361,11 @@ class Embed:
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The name of the author.
-        url: str
+        url: :class:`str`
             The URL for the author.
-        icon_url: str
+        icon_url: :class:`str`
             The URL of the author icon. Only HTTP(S) is supported.
         """
 
@@ -399,11 +399,11 @@ class Embed:
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The name of the field.
-        value: str
+        value: :class:`str`
             The value of the field.
-        inline: bool
+        inline: :class:`bool`
             Whether the field should be displayed inline.
         """
 
@@ -440,7 +440,7 @@ class Embed:
 
         Parameters
         -----------
-        index: int
+        index: :class:`int`
             The index of the field to remove.
         """
         try:
@@ -458,13 +458,13 @@ class Embed:
 
         Parameters
         -----------
-        index: int
+        index: :class:`int`
             The index of the field to modify.
-        name: str
+        name: :class:`str`
             The name of the field.
-        value: str
+        value: :class:`str`
             The value of the field.
-        inline: bool
+        inline: :class:`bool`
             Whether the field should be displayed inline.
 
         Raises

discord/emoji.py

@@ -224,7 +224,7 @@ class Emoji:
 
         Parameters
         -----------
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for deleting this emoji. Shows up on the audit log.
 
         Raises
@@ -247,11 +247,11 @@ class Emoji:
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The new emoji name.
         roles: Optional[list[:class:`Role`]]
             A :class:`list` of :class:`Role`\s that can use this emoji. Leave empty to make it available to everyone.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for editing this emoji. Shows up on the audit log.
 
         Raises

discord/ext/commands/bot.py

@@ -208,7 +208,7 @@ class BotBase(GroupMixin):
         -----------
         func
             The function that was used as a global check.
-        call_once: bool
+        call_once: :class:`bool`
             If the function should only be called once per
             :meth:`.Command.invoke` call.
         """
@@ -228,7 +228,7 @@ class BotBase(GroupMixin):
         -----------
         func
             The function to remove from the global checks.
-        call_once: bool
+        call_once: :class:`bool`
             If the function was added with ``call_once=True`` in
             the :meth:`.Bot.add_check` call or using :meth:`.check_once`.
         """
@@ -370,9 +370,9 @@ class BotBase(GroupMixin):
 
         Parameters
         -----------
-        func : :ref:`coroutine <coroutine>`
+        func: :ref:`coroutine <coroutine>`
             The function to call.
-        name : Optional[str]
+        name: Optional[:class:`str`]
             The name of the event to listen for. Defaults to ``func.__name__``.
 
         Example
@@ -404,7 +404,7 @@ class BotBase(GroupMixin):
         -----------
         func
             The function that was used as a listener to remove.
-        name
+        name: :class:`str`
             The name of the event we want to remove. Defaults to
             ``func.__name__``.
         """
@@ -462,7 +462,7 @@ class BotBase(GroupMixin):
 
         Parameters
         -----------
-        cog
+        cog: :class:`.Cog`
             The cog to register to the bot.
 
         Raises
@@ -486,7 +486,7 @@ class BotBase(GroupMixin):
 
         Parameters
         -----------
-        name : str
+        name: :class:`str`
             The name of the cog you are requesting.
             This is equivalent to the name passed via keyword
             argument in class creation or the class name if unspecified.
@@ -535,7 +535,7 @@ class BotBase(GroupMixin):
 
         Parameters
         ------------
-        name: str
+        name: :class:`str`
             The extension name to load. It must be dot separated like
             regular Python imports if accessing a sub-module. e.g.
             ``foo.test`` if you want to import ``foo/test.py``.
@@ -573,7 +573,7 @@ class BotBase(GroupMixin):
 
         Parameters
         ------------
-        name: str
+        name: :class:`str`
             The extension name to unload. It must be dot separated like
             regular Python imports if accessing a sub-module. e.g.
             ``foo.test`` if you want to import ``foo/test.py``.
@@ -668,7 +668,7 @@ class BotBase(GroupMixin):
 
         Returns
         --------
-        Union[List[str], str]
+        Union[List[:class:`str`], :class:`str`]
             A list of prefixes or a single prefix that the bot is
             listening for.
         """
@@ -857,7 +857,7 @@ class Bot(BotBase, discord.Client):
         .. note::
 
             When passing multiple prefixes be careful to not pass a prefix
-            that matches a longer prefix occuring later in the sequence.  For
+            that matches a longer prefix occurring later in the sequence.  For
             example, if the command prefix is ``('!', '!?')``  the ``'!?'``
             prefix will never be matched to any message as the previous one
             matches messages starting with ``!?``. This is especially important

discord/ext/commands/cog.py

@@ -174,7 +174,7 @@ class Cog(metaclass=CogMeta):
                 # Get the latest parent reference
                 parent = lookup[parent.qualified_name]
 
-                # Update our parent's reference to ourself
+                # Update our parent's reference to our self
                 removed = parent.remove_command(command.name)
                 parent.add_command(command)
 

discord/ext/commands/context.py

@@ -145,9 +145,9 @@ class Context(discord.abc.Messageable):
 
         Parameters
         ------------
-        call_hooks: bool
+        call_hooks: :class:`bool`
             Whether to call the before and after invoke hooks.
-        restart: bool
+        restart: :class:`bool`
             Whether to start the call chain from the very beginning
             or where we left off (i.e. the command that caused the error).
             The default is to start where we left off.
@@ -241,7 +241,7 @@ class Context(discord.abc.Messageable):
 
             Due to the way this function works, instead of returning
             something similar to :meth:`~.commands.HelpCommand.command_not_found`
-            this returns :obj:`None` on bad input or no help command.
+            this returns :class:`None` on bad input or no help command.
 
         Parameters
         ------------

discord/ext/commands/converter.py

@@ -69,7 +69,7 @@ class Converter:
         -----------
         ctx: :class:`.Context`
             The invocation context that the argument is being used in.
-        argument: str
+        argument: :class:`str`
             The argument that is being converted.
         """
         raise NotImplementedError('Derived classes need to implement this.')
@@ -304,7 +304,6 @@ class ColourConverter(Converter):
 class RoleConverter(IDConverter):
     """Converts to a :class:`Role`.
 
-
     All lookups are via the local guild. If in a DM context, then the lookup
     is done by the global cache.
 
@@ -349,7 +348,6 @@ class InviteConverter(Converter):
 class EmojiConverter(IDConverter):
     """Converts to a :class:`Emoji`.
 
-
     All lookups are done for the local guild first, if available. If that lookup
     fails, then it checks the client's global cache.
 
@@ -390,7 +388,6 @@ class EmojiConverter(IDConverter):
 class PartialEmojiConverter(Converter):
     """Converts to a :class:`PartialEmoji`.
 
-
     This is done by extracting the animated flag, name and ID from the emoji.
     """
     async def convert(self, ctx, argument):
@@ -413,11 +410,11 @@ class clean_content(Converter):
 
     Attributes
     ------------
-    fix_channel_mentions: :obj:`bool`
+    fix_channel_mentions: :class:`bool`
         Whether to clean channel mentions.
-    use_nicknames: :obj:`bool`
+    use_nicknames: :class:`bool`
         Whether to use nicknames when transforming mentions.
-    escape_markdown: :obj:`bool`
+    escape_markdown: :class:`bool`
         Whether to also escape special markdown characters.
     """
     def __init__(self, *, fix_channel_mentions=False, use_nicknames=True, escape_markdown=False):

discord/ext/commands/core.py

@@ -651,7 +651,7 @@ class Command(_BaseCommand):
 
         Returns
         --------
-        bool
+        :class:`bool`
             A boolean indicating if the command is on cooldown.
         """
         if not self._buckets.valid:
@@ -708,7 +708,7 @@ class Command(_BaseCommand):
 
         Parameters
         -----------
-        coro : :ref:`coroutine <coroutine>`
+        coro: :ref:`coroutine <coroutine>`
             The coroutine to register as the local error handler.
 
         Raises
@@ -736,7 +736,7 @@ class Command(_BaseCommand):
 
         Parameters
         -----------
-        coro
+        coro: :ref:`coroutine <coroutine>`
             The coroutine to register as the pre-invoke hook.
 
         Raises
@@ -763,7 +763,7 @@ class Command(_BaseCommand):
 
         Parameters
         -----------
-        coro
+        coro: :ref:`coroutine <coroutine>`
             The coroutine to register as the post-invoke hook.
 
         Raises
@@ -863,7 +863,7 @@ class Command(_BaseCommand):
 
         Returns
         --------
-        bool
+        :class:`bool`
             A boolean indicating if the command can be invoked.
         """
 
@@ -963,7 +963,7 @@ class GroupMixin:
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The name of the command to remove.
 
         Returns
@@ -1006,12 +1006,12 @@ class GroupMixin:
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The name of the command to get.
 
         Returns
         --------
-        Command or subclass
+        :class:`Command` or subclass
             The command that was requested. If not found, returns ``None``.
         """
 
@@ -1170,7 +1170,7 @@ def command(name=None, cls=None, **attrs):
 
     Parameters
     -----------
-    name: str
+    name: :class:`str`
         The name to create the command with. By default this uses the
         function name unchanged.
     cls
@@ -1221,11 +1221,6 @@ def check(predicate):
 
         These functions can either be regular functions or coroutines.
 
-    Parameters
-    -----------
-    predicate
-        The predicate to check if the command should be invoked.
-
     Examples
     ---------
 
@@ -1255,6 +1250,10 @@ def check(predicate):
         async def only_me(ctx):
             await ctx.send('Only you!')
 
+    Parameters
+    -----------
+    predicate: Callable[:class:`Context`, :class:`bool`]
+        The predicate to check if the command should be invoked.
     """
 
     def decorator(func):
@@ -1283,7 +1282,7 @@ def has_role(item):
 
     Parameters
     -----------
-    item: Union[int, str]
+    item: Union[:class:`int`, :class:`str`]
         The name or ID of the role to check.
     """
 
@@ -1308,7 +1307,7 @@ def has_any_role(*items):
 
     Parameters
     -----------
-    items
+    items: List[Union[:class:`str`, :class:`int`]]
         An argument list of names or IDs to check that the member has roles wise.
 
     Example
@@ -1482,9 +1481,9 @@ def cooldown(rate, per, type=BucketType.default):
 
     Parameters
     ------------
-    rate: int
+    rate: :class:`int`
         The number of times a command can be used before triggering a cooldown.
-    per: float
+    per: :class:`float`
         The amount of seconds to wait for a cooldown when it's been triggered.
     type: ``BucketType``
         The type of cooldown to have.

discord/ext/commands/help.py

@@ -107,9 +107,9 @@ class Paginator:
 
         Parameters
         -----------
-        line: str
+        line: :class:`str`
             The line to add.
-        empty: bool
+        empty: :class:`bool`
             Indicates if another empty line should be added.
 
         Raises
@@ -725,7 +725,6 @@ class HelpCommand:
         - :meth:`send_error_message`
         - :meth:`on_help_command_error`
         - :meth:`prepare_help_command`
-
         """
         await self.prepare_help_command(ctx, command)
         bot = ctx.bot

discord/gateway.py

@@ -256,7 +256,7 @@ class DiscordWebSocket(websockets.client.WebSocketClientProtocol):
 
         Parameters
         -----------
-        event : str
+        event: :class:`str`
             The event name in all upper case to wait for.
         predicate
             A function that takes a data parameter to check for event
@@ -445,7 +445,7 @@ class DiscordWebSocket(websockets.client.WebSocketClientProtocol):
 
     @property
     def latency(self):
-        """:obj:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds."""
+        """:class:`float`: Measures latency between a HEARTBEAT and a HEARTBEAT_ACK in seconds."""
         heartbeat = self._keep_alive
         return float('inf') if heartbeat is None else heartbeat.latency
 

discord/guild.py

@@ -422,20 +422,20 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        format: str
+        format: :class:`str`
             The format to attempt to convert the icon to.
-        size: int
+        size: :class:`int`
             The size of the image to display.
 
-        Returns
-        --------
-        str
-            The resulting CDN URL.
-
         Raises
         ------
         InvalidArgument
             Bad image format passed to ``format`` or invalid ``size``.
+
+        Returns
+        --------
+        :class:`str`
+            The resulting CDN URL.
         """
         if not valid_icon_size(size):
             raise InvalidArgument("size must be a power of 2 between 16 and 4096")
@@ -460,20 +460,20 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        format: str
+        format: :class:`str`
             The format to attempt to convert the banner to.
-        size: int
+        size: :class:`int`
             The size of the image to display.
 
-        Returns
-        --------
-        str
-            The resulting CDN URL.
-
         Raises
         ------
         InvalidArgument
             Bad image format passed to ``format`` or invalid ``size``.
+
+        Returns
+        --------
+        :class:`str`
+            The resulting CDN URL.
         """
         if not valid_icon_size(size):
             raise InvalidArgument("size must be a power of 2 between 16 and 4096")
@@ -498,20 +498,20 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        format: str
+        format: :class:`str`
             The format to attempt to convert the splash to.
-        size: int
+        size: :class:`int`
             The size of the image to display.
 
-        Returns
-        --------
-        str
-            The resulting CDN URL.
-
         Raises
         ------
         InvalidArgument
             Bad image format passed to ``format`` or invalid ``size``.
+
+        Returns
+        --------
+        :class:`str`
+            The resulting CDN URL.
         """
         if not valid_icon_size(size):
             raise InvalidArgument("size must be a power of 2 between 16 and 4096")
@@ -573,7 +573,7 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The name of the member to lookup with an optional discriminator.
 
         Returns
@@ -649,8 +649,8 @@ class Guild(Hashable):
         overwrites with the target (either a :class:`Member` or a :class:`Role`)
         as the key and a :class:`PermissionOverwrite` as the value.
 
-        Note
+        .. note::
-        --------
+
             Creating a channel of a specified position will not update the position of
             other channels to follow suit. A follow-up call to :meth:`~TextChannel.edit`
             will be required to update the position of the channel in the channel list.
@@ -765,8 +765,8 @@ class Guild(Hashable):
 
         Leaves the guild.
 
-        Note
+        .. note::
-        --------
+
             You cannot leave the guild that you own, you must delete it instead
             via :meth:`delete`.
 
@@ -803,18 +803,18 @@ class Guild(Hashable):
 
         Parameters
         ----------
-        name: str
+        name: :class:`str`
             The new name of the guild.
-        description: str
+        description: :class:`str`
             The new description of the guild. This is only available to guilds that
             contain `VERIFIED` in :attr:`Guild.features`.
-        icon: bytes
+        icon: :class:`bytes`
             A :term:`py:bytes-like object` representing the icon. Only PNG/JPEG supported.
             Could be ``None`` to denote removal of the icon.
-        banner: bytes
+        banner: :class:`bytes`
             A :term:`py:bytes-like object` representing the banner.
             Could be ``None`` to denote removal of the banner.
-        splash: bytes
+        splash: :class:`bytes`
             A :term:`py:bytes-like object` representing the invite splash.
             Only PNG/JPEG supported. Could be ``None`` to denote removing the
             splash. Only available for partnered guilds with ``INVITE_SPLASH``
@@ -823,7 +823,7 @@ class Guild(Hashable):
             The new region for the guild's voice communication.
         afk_channel: Optional[:class:`VoiceChannel`]
             The new channel that is the AFK channel. Could be ``None`` for no AFK channel.
-        afk_timeout: int
+        afk_timeout: :class:`int`
             The number of seconds until someone is moved to the AFK channel.
         owner: :class:`Member`
             The new owner of the guild to transfer ownership to. Note that you must
@@ -834,11 +834,11 @@ class Guild(Hashable):
             The new default notification level for the guild.
         explicit_content_filter: :class:`ContentFilter`
             The new explicit content filter for the guild.
-        vanity_code: str
+        vanity_code: :class:`str`
             The new vanity code for the guild.
         system_channel: Optional[:class:`TextChannel`]
             The new channel that is used for the system channel. Could be ``None`` for no system channel.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for editing this guild. Shows up on the audit log.
 
         Raises
@@ -1026,9 +1026,9 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        days: int
+        days: :class:`int`
             The number of days before counting as inactive.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for doing this action. Shows up on the audit log.
 
         Raises
@@ -1042,7 +1042,7 @@ class Guild(Hashable):
 
         Returns
         ---------
-        int
+        :class:`int`
             The number of members pruned.
         """
 
@@ -1082,7 +1082,7 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        days: int
+        days: :class:`int`
             The number of days before counting as inactive.
 
         Raises
@@ -1096,7 +1096,7 @@ class Guild(Hashable):
 
         Returns
         ---------
-        int
+        :class:`int`
             The number of members estimated to be pruned.
         """
 
@@ -1150,27 +1150,27 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The emoji name. Must be at least 2 characters.
-        image: bytes
+        image: :class:`bytes`
             The :term:`py:bytes-like object` representing the image data to use.
             Only JPG, PNG and GIF images are supported.
-        roles: Optional[list[:class:`Role`]]
+        roles: Optional[List[:class:`Role`]]
             A :class:`list` of :class:`Role`\s that can use this emoji. Leave empty to make it available to everyone.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for creating this emoji. Shows up on the audit log.
 
-        Returns
-        --------
-        :class:`Emoji`
-            The created emoji.
-
         Raises
         -------
         Forbidden
             You are not allowed to create emojis.
         HTTPException
             An error occurred creating an emoji.
+
+        Returns
+        --------
+        :class:`Emoji`
+            The created emoji.
         """
 
         img = utils._bytes_to_base64_data(image)
@@ -1191,27 +1191,22 @@ class Guild(Hashable):
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The role name. Defaults to 'new role'.
         permissions: :class:`Permissions`
             The permissions to have. Defaults to no permissions.
         colour: :class:`Colour`
             The colour for the role. Defaults to :meth:`Colour.default`.
             This is aliased to ``color`` as well.
-        hoist: bool
+        hoist: :class:`bool`
             Indicates if the role should be shown separately in the member list.
             Defaults to False.
-        mentionable: bool
+        mentionable: :class:`bool`
             Indicates if the role should be mentionable by others.
             Defaults to False.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for creating this role. Shows up on the audit log.
 
-        Returns
-        --------
-        :class:`Role`
-            The newly created role.
-
         Raises
         -------
         Forbidden
@@ -1220,6 +1215,11 @@ class Guild(Hashable):
             Editing the role failed.
         InvalidArgument
             An invalid keyword argument was given.
+
+        Returns
+        --------
+        :class:`Role`
+            The newly created role.
         """
 
         try:
@@ -1261,7 +1261,7 @@ class Guild(Hashable):
         -----------
         user: :class:`abc.Snowflake`
             The user to kick from their guild.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason the user got kicked.
 
         Raises
@@ -1287,10 +1287,10 @@ class Guild(Hashable):
         -----------
         user: :class:`abc.Snowflake`
             The user to ban from their guild.
-        delete_message_days: int
+        delete_message_days: :class:`int`
             The number of days worth of messages to delete from the user
             in the guild. The minimum is 0 and the maximum is 7.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason the user got banned.
 
         Raises
@@ -1316,7 +1316,7 @@ class Guild(Hashable):
         -----------
         user: :class:`abc.Snowflake`
             The user to unban.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for doing this action. Shows up on the audit log.
 
         Raises
@@ -1339,17 +1339,17 @@ class Guild(Hashable):
         You must have the :attr:`~Permissions.manage_guild` permission to use
         this as well.
 
-        Returns
-        --------
-        :class:`Invite`
-            The special vanity invite.
-
         Raises
         -------
         Forbidden
             You do not have the proper permissions to get this.
         HTTPException
             Retrieving the vanity invite failed.
+
+        Returns
+        --------
+        :class:`Invite`
+            The special vanity invite.
         """
 
         # we start with { code: abc }
@@ -1392,38 +1392,6 @@ class Guild(Hashable):
 
         You must have the :attr:`~Permissions.view_audit_log` permission to use this.
 
-        Parameters
-        -----------
-        limit: Optional[int]
-            The number of entries to retrieve. If ``None`` retrieve all entries.
-        before: Union[:class:`abc.Snowflake`, datetime]
-            Retrieve entries before this date or entry.
-            If a date is provided it must be a timezone-naive datetime representing UTC time.
-        after: Union[:class:`abc.Snowflake`, datetime]
-            Retrieve entries after this date or entry.
-            If a date is provided it must be a timezone-naive datetime representing UTC time.
-        reverse: bool
-            If set to true, return entries in oldest->newest order. If unspecified,
-            this defaults to ``False`` for most cases. However if passing in a
-            ``after`` parameter then this is set to ``True``. This avoids getting entries
-            out of order in the ``after`` case.
-        user: :class:`abc.Snowflake`
-            The moderator to filter entries from.
-        action: :class:`AuditLogAction`
-            The action to filter with.
-
-        Yields
-        --------
-        :class:`AuditLogEntry`
-            The audit log entry.
-
-        Raises
-        -------
-        Forbidden
-            You are not allowed to fetch audit logs
-        HTTPException
-            An error occurred while fetching the audit logs.
-
         Examples
         ----------
 
@@ -1441,6 +1409,38 @@ class Guild(Hashable):
 
             entries = await guild.audit_logs(limit=None, user=guild.me).flatten()
             await channel.send('I made {} moderation actions.'.format(len(entries)))
+
+        Parameters
+        -----------
+        limit: Optional[:class:`int`]
+            The number of entries to retrieve. If ``None`` retrieve all entries.
+        before: Union[:class:`abc.Snowflake`, datetime]
+            Retrieve entries before this date or entry.
+            If a date is provided it must be a timezone-naive datetime representing UTC time.
+        after: Union[:class:`abc.Snowflake`, datetime]
+            Retrieve entries after this date or entry.
+            If a date is provided it must be a timezone-naive datetime representing UTC time.
+        reverse: :class:`bool`
+            If set to true, return entries in oldest->newest order. If unspecified,
+            this defaults to ``False`` for most cases. However if passing in a
+            ``after`` parameter then this is set to ``True``. This avoids getting entries
+            out of order in the ``after`` case.
+        user: :class:`abc.Snowflake`
+            The moderator to filter entries from.
+        action: :class:`AuditLogAction`
+            The action to filter with.
+
+        Raises
+        -------
+        Forbidden
+            You are not allowed to fetch audit logs
+        HTTPException
+            An error occurred while fetching the audit logs.
+
+        Yields
+        --------
+        :class:`AuditLogEntry`
+            The audit log entry.
         """
         if user:
             user = user.id

discord/invite.py

@@ -314,7 +314,7 @@ class Invite(Hashable):
 
         Parameters
         -----------
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for deleting this invite. Shows up on the audit log.
 
         Raises

discord/iterators.py

@@ -186,17 +186,17 @@ class HistoryIterator(_AsyncIterator):
     Parameters
     -----------
     messageable: :class:`abc.Messageable`
-        Messageable class to retrieve message history fro.
+        Messageable class to retrieve message history from.
-    limit : int
+    limit: :class:`int`
         Maximum number of messages to retrieve
-    before : :class:`Message` or id-like
+    before: :class:`abc.Snowflake`
         Message before which all messages must be.
-    after : :class:`Message` or id-like
+    after: :class:`abc.Snowflake`
         Message after which all messages must be.
-    around : :class:`Message` or id-like
+    around: :class:`abc.Snowflake`
         Message around which all messages must be. Limit max 101. Note that if
         limit is an even number, this will return at most limit+1 messages.
-    reverse: bool
+    reverse: :class:`bool`
         If set to true, return messages in oldest->newest order. Recommended
         when using with "after" queries with limit over 100, otherwise messages
         will be out of order.

discord/member.py

@@ -366,7 +366,7 @@ class Member(discord.abc.Messageable, _BaseUser):
 
         Parameters
         -----------
-        channel
+        channel: :class:`Channel`
             The channel to check your permissions for.
         """
         return channel.permissions_for(self)
@@ -457,17 +457,17 @@ class Member(discord.abc.Messageable, _BaseUser):
 
         Parameters
         -----------
-        nick: str
+        nick: Optional[:class:`str`]
             The member's new nickname. Use ``None`` to remove the nickname.
-        mute: bool
+        mute: Optional[:class:`bool`]
             Indicates if the member should be guild muted or un-muted.
-        deafen: bool
+        deafen: Optional[:class:`bool`]
             Indicates if the member should be guild deafened or un-deafened.
-        roles: List[:class:`Roles`]
+        roles: Optional[List[:class:`Roles`]]
             The member's new list of roles. This *replaces* the roles.
-        voice_channel: :class:`VoiceChannel`
+        voice_channel: Optional[:class:`VoiceChannel`]
             The voice channel to move the member to.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for editing this member. Shows up on the audit log.
 
         Raises
@@ -533,7 +533,7 @@ class Member(discord.abc.Messageable, _BaseUser):
         -----------
         channel: :class:`VoiceChannel`
             The new voice channel to move the member to.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for doing this action. Shows up on the audit log.
         """
         await self.edit(voice_channel=channel, reason=reason)
@@ -548,10 +548,10 @@ class Member(discord.abc.Messageable, _BaseUser):
 
         Parameters
         -----------
-        \*roles
+        \*roles: :class:`Snowflake`
             An argument list of :class:`abc.Snowflake` representing a :class:`Role`
             to give to the member.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for adding these roles. Shows up on the audit log.
         atomic: bool
             Whether to atomically add roles. This will ensure that multiple
@@ -586,12 +586,12 @@ class Member(discord.abc.Messageable, _BaseUser):
 
         Parameters
         -----------
-        \*roles
+        \*roles: :class:`Snowflake`
             An argument list of :class:`abc.Snowflake` representing a :class:`Role`
             to remove from the member.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for removing these roles. Shows up on the audit log.
-        atomic: bool
+        atomic: :class:`bool`
             Whether to atomically remove roles. This will ensure that multiple
             operations will always be applied regardless of the current
             state of the cache.

discord/message.py

@@ -108,7 +108,7 @@ class Attachment:
 
         Returns
         --------
-        int
+        :class:`int`
             The number of bytes written.
         """
         url = self.proxy_url if use_cached else self.url
@@ -583,13 +583,13 @@ class Message:
 
         Parameters
         -----------
-        content: Optional[str]
+        content: Optional[:class:`str`]
             The new content to replace the message with.
             Could be ``None`` to remove the content.
         embed: Optional[:class:`Embed`]
             The new embed to replace the original with.
             Could be ``None`` to remove the embed.
-        delete_after: Optional[float]
+        delete_after: Optional[:class:`float`]
             If provided, the number of seconds to wait in the background
             before deleting the message we just edited. If the deletion fails,
             then it is silently ignored.
@@ -690,7 +690,7 @@ class Message:
 
         Parameters
         ------------
-        emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, str]
+        emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, :class:`str`]
             The emoji to react with.
 
         Raises
@@ -723,7 +723,7 @@ class Message:
 
         Parameters
         ------------
-        emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, str]
+        emoji: Union[:class:`Emoji`, :class:`Reaction`, :class:`PartialEmoji`, :class:`str`]
             The emoji to remove.
         member: :class:`abc.Snowflake`
             The member for which to remove the reaction.

discord/object.py

@@ -57,7 +57,7 @@ class Object(Hashable):
 
     Attributes
     -----------
-    id : :class:`str`
+    id: :class:`str`
         The ID of the object.
     """
 

discord/opus.py

@@ -125,15 +125,15 @@ def load_opus(name):
 
     This function propagates the exceptions thrown.
 
-    Warning
+    .. warning::
-    --------
+
         The bitness of the library must match the bitness of your python
         interpreter. If the library is 64-bit then your python interpreter
         must be 64-bit as well. Usually if there's a mismatch in bitness then
         the load will throw an exception.
 
-    Note
+    .. note::
-    ----
+
         On Windows, the .dll extension is not necessary. However, on Linux
         the full extension is required to load the library, e.g. ``libopus.so.1``.
         On Linux however, `find library`_ will usually find the library automatically
@@ -141,7 +141,7 @@ def load_opus(name):
 
     Parameters
     ----------
-    name: str
+    name: :class:`str`
         The filename of the shared library.
     """
     global _lib
@@ -155,7 +155,7 @@ def is_loaded():
 
     Returns
     -------
-    bool
+    :class:`bool`
         Indicates if the opus library has been loaded.
     """
     global _lib
@@ -166,7 +166,7 @@ class OpusError(DiscordException):
 
     Attributes
     ----------
-    code : :class:`int`
+    code: :class:`int`
         The error code returned.
     """
 

discord/player.py

@@ -65,7 +65,7 @@ class AudioSource:
 
         Returns
         --------
-        bytes
+        :class:`bytes`
             A bytes like object that represents the PCM or Opus data.
         """
         raise NotImplementedError
@@ -117,21 +117,21 @@ class FFmpegPCMAudio(AudioSource):
 
     Parameters
     ------------
-    source: Union[str, BinaryIO]
+    source: Union[:class:`str`, BinaryIO]
         The input that ffmpeg will take and convert to PCM bytes.
         If ``pipe`` is True then this is a file-like object that is
         passed to the stdin of ffmpeg.
-    executable: str
+    executable: :class:`str`
         The executable name (and path) to use. Defaults to ``ffmpeg``.
-    pipe: bool
+    pipe: :class:`bool`
         If true, denotes that ``source`` parameter will be passed
         to the stdin of ffmpeg. Defaults to ``False``.
     stderr: Optional[BinaryIO]
         A file-like object to pass to the Popen constructor.
         Could also be an instance of ``subprocess.PIPE``.
-    options: Optional[str]
+    options: Optional[:class:`str`]
         Extra command line arguments to pass to ffmpeg after the ``-i`` flag.
-    before_options: Optional[str]
+    before_options: Optional[:class:`str`]
         Extra command line arguments to pass to ffmpeg before the ``-i`` flag.
 
     Raises

discord/reaction.py

@@ -127,20 +127,6 @@ class Reaction:
         The ``after`` parameter must represent a member
         and meet the :class:`abc.Snowflake` abc.
 
-        Parameters
-        ------------
-        limit: int
-            The maximum number of results to return.
-            If not provided, returns all the users who
-            reacted to the message.
-        after: :class:`abc.Snowflake`
-            For pagination, reactions are sorted by member.
-
-        Raises
-        --------
-        HTTPException
-            Getting the users for the reaction failed.
-
         Examples
         ---------
 
@@ -157,6 +143,20 @@ class Reaction:
             winner = random.choice(users)
             await channel.send('{} has won the raffle.'.format(winner))
 
+        Parameters
+        ------------
+        limit: :class:`int`
+            The maximum number of results to return.
+            If not provided, returns all the users who
+            reacted to the message.
+        after: :class:`abc.Snowflake`
+            For pagination, reactions are sorted by member.
+
+        Raises
+        --------
+        HTTPException
+            Getting the users for the reaction failed.
+
         Yields
         --------
         Union[:class:`User`, :class:`Member`]

discord/role.py

@@ -211,20 +211,20 @@ class Role(Hashable):
 
         Parameters
         -----------
-        name: str
+        name: :class:`str`
             The new role name to change to.
         permissions: :class:`Permissions`
             The new permissions to change to.
         colour: :class:`Colour`
             The new colour to change to. (aliased to color as well)
-        hoist: bool
+        hoist: :class:`bool`
             Indicates if the role should be shown separately in the member list.
-        mentionable: bool
+        mentionable: :class:`bool`
             Indicates if the role should be mentionable by others.
-        position: int
+        position: :class:`int`
             The new role's position. This must be below your top role's
             position or it will fail.
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for editing this role. Shows up on the audit log.
 
         Raises
@@ -269,7 +269,7 @@ class Role(Hashable):
 
         Parameters
         -----------
-        reason: Optional[str]
+        reason: Optional[:class:`str`]
             The reason for deleting this role. Shows up on the audit log.
 
         Raises

discord/shard.py

@@ -192,7 +192,7 @@ class AutoShardedClient(Client):
 
         Parameters
         -----------
-        \*guilds
+        \*guilds: :class:`Guild`
             An argument list of guilds to request offline members for.
 
         Raises
@@ -313,11 +313,11 @@ class AutoShardedClient(Client):
         status: Optional[:class:`Status`]
             Indicates what status to change to. If None, then
             :attr:`Status.online` is used.
-        afk: bool
+        afk: :class:`bool`
             Indicates if you are going AFK. This allows the discord
             client to know how to handle push notifications better
             for you in case you are actually idle and not lying.
-        shard_id: Optional[int]
+        shard_id: Optional[:class:`int`]
             The shard_id to change the presence to. If not specified
             or ``None``, then it will change the presence of every
             shard the bot can see.

discord/user.py

@@ -139,27 +139,27 @@ class BaseUser(_BaseUser):
 
         Parameters
         -----------
-        format: Optional[str]
+        format: Optional[:class:`str`]
             The format to attempt to convert the avatar to.
             If the format is ``None``, then it is automatically
             detected into either 'gif' or static_format depending on the
             avatar being animated or not.
-        static_format: 'str'
+        static_format: Optional[:class:`str`]
             Format to attempt to convert only non-animated avatars to.
             Defaults to 'webp'
-        size: int
+        size: :class:`int`
             The size of the image to display.
 
-        Returns
-        --------
-        str
-            The resulting CDN URL.
-
         Raises
         ------
         InvalidArgument
             Bad image format passed to ``format`` or ``static_format``, or
             invalid ``size``.
+
+        Returns
+        --------
+        :class:`str`
+            The resulting CDN URL.
         """
         if not valid_icon_size(size):
             raise InvalidArgument("size must be a power of 2 between 16 and 1024")
@@ -218,7 +218,7 @@ class BaseUser(_BaseUser):
 
         Parameters
         -----------
-        channel
+        channel: :class:`abc.GuildChannel`
             The channel to check your permissions for.
         """
         return channel.permissions_for(self)
@@ -245,7 +245,7 @@ class BaseUser(_BaseUser):
 
         Parameters
         -----------
-        message : :class:`Message`
+        message: :class:`Message`
             The message to check if you're mentioned in.
         """
 
@@ -323,7 +323,7 @@ class ClientUser(BaseUser):
 
         Parameters
         -----------
-        user_id: int
+        user_id: :class:`int`
             The user ID to check if we have a relationship with them.
 
         Returns
@@ -367,22 +367,22 @@ class ClientUser(BaseUser):
 
         Parameters
         -----------
-        password : str
+        password: :class:`str`
             The current password for the client's account.
             Only applicable to user accounts.
-        new_password: str
+        new_password: :class:`str`
             The new password you wish to change to.
             Only applicable to user accounts.
-        email: str
+        email: :class:`str`
             The new email you wish to change to.
             Only applicable to user accounts.
         house: Optional[:class:`HypeSquadHouse`]
             The hypesquad house you wish to change to.
             Could be ``None`` to leave the current house.
             Only applicable to user accounts.
-        username :str
+        username: :class:`str`
             The new username you wish to change to.
-        avatar: bytes
+        avatar: :class:`bytes`
             A :term:`py:bytes-like object` representing the image to upload.
             Could be ``None`` to denote no avatar.
 
@@ -459,15 +459,10 @@ class ClientUser(BaseUser):
 
         Parameters
         -----------
-        \*recipients
+        \*recipients: :class:`User`
             An argument :class:`list` of :class:`User` to have in
             your group.
 
-        Return
-        -------
-        :class:`GroupChannel`
-            The new group channel.
-
         Raises
         -------
         HTTPException
@@ -475,6 +470,11 @@ class ClientUser(BaseUser):
         ClientException
             Attempted to create a group with only one recipient.
             This does not include yourself.
+
+        Returns
+        -------
+        :class:`GroupChannel`
+            The new group channel.
         """
 
         from .channel import GroupChannel
@@ -563,17 +563,17 @@ class User(BaseUser, discord.abc.Messageable):
 
         Gets all mutual friends of this user. This can only be used by non-bot accounts
 
-        Returns
-        -------
-        List[:class:`User`]
-            The users that are mutual friends.
-
         Raises
         -------
         Forbidden
             Not allowed to get mutual friends of this user.
         HTTPException
             Getting mutual friends failed.
+
+        Returns
+        -------
+        List[:class:`User`]
+            The users that are mutual friends.
         """
         state = self._state
         mutuals = await state.http.get_mutual_friends(self.id)

discord/utils.py

@@ -104,14 +104,14 @@ def oauth_url(client_id, permissions=None, guild=None, redirect_uri=None):
 
     Parameters
     -----------
-    client_id : str
+    client_id: :class:`str`
         The client ID for your bot.
-    permissions : :class:`Permissions`
+    permissions: :class:`Permissions`
         The permissions you're requesting. If not given then you won't be requesting any
         permissions.
-    guild : :class:`Guild`
+    guild: :class:`Guild`
         The guild to pre-select in the authorization screen, if available.
-    redirect_uri : str
+    redirect_uri: :class:`str`
         An optional valid redirect URI.
     """
     url = 'https://discordapp.com/oauth2/authorize?client_id={}&scope=bot'.format(client_id)
@@ -139,7 +139,7 @@ def time_snowflake(datetime_obj, high=False):
     -----------
     datetime_obj
         A timezone-naive datetime object representing UTC time.
-    high
+    high: :class:`bool`
         Whether or not to set the lower 22 bit to high or low.
     """
     unix_seconds = (datetime_obj - type(datetime_obj)(1970, 1, 1)).total_seconds()
@@ -166,7 +166,7 @@ def find(predicate, seq):
     -----------
     predicate
         A function that returns a boolean-like result.
-    seq : iterable
+    seq: iterable
         The iterable to search through.
     """
 

discord/webhook.py

@@ -61,17 +61,17 @@ class WebhookAdapter:
 
         Parameters
         -----------
-        verb: str
+        verb: :class:`str`
             The HTTP verb to use for the request.
-        url: str
+        url: :class:`str`
             The URL to send the request to. This will have
             the query parameters already added to it, if any.
-        multipart: Optional[dict]
+        multipart: Optional[:class:`dict`]
             A dict containing multipart form data to send with
             the request. If a filename is being uploaded, then it will
             be under a ``file`` key which will have a 3-element :class:`tuple`
             denoting ``(filename, file, content_type)``.
-        payload: Optional[dict]
+        payload: Optional[:class:`dict`]
             The JSON to send with the request, if any.
         """
         raise NotImplementedError()
@@ -95,7 +95,7 @@ class WebhookAdapter:
         ------------
         data
             The data that was returned from the request.
-        wait: bool
+        wait: :class:`bool`
             Whether the webhook execution was asked to wait or not.
         """
         raise NotImplementedError()
@@ -235,7 +235,7 @@ class RequestsWebhookAdapter(WebhookAdapter):
         each request will create a new session. Note if a session is given,
         the webhook adapter **will not** clean it up for you. You must close
         the session yourself.
-    sleep: bool
+    sleep: :class:`bool`
         Whether to sleep the thread when encountering a 429 or pre-emptive
         rate limit or a 5xx status code. Defaults to ``True``. If set to
         ``False`` then this will raise an :exc:`HTTPException` instead.
@@ -441,9 +441,9 @@ class Webhook:
 
         Parameters
         -----------
-        id: int
+        id: :class:`int`
             The ID of the webhook.
-        token: str
+        token: :class:`str`
             The authentication token of the webhook.
         adapter: :class:`WebhookAdapter`
             The webhook adapter to use when sending requests. This is
@@ -467,7 +467,7 @@ class Webhook:
 
         Parameters
         ------------
-        url: str
+        url: :class:`str`
             The URL of the webhook.
         adapter: :class:`WebhookAdapter`
             The webhook adapter to use when sending requests. This is
@@ -534,21 +534,21 @@ class Webhook:
 
         Parameters
         -----------
-        format: Optional[str]
+        format: Optional[:class:`str`]
             The format to attempt to convert the avatar to.
             If the format is ``None``, then it is equivalent to png.
-        size: int
+        size: :class:`int`
             The size of the image to display.
 
-        Returns
-        --------
-        str
-            The resulting CDN URL.
-
         Raises
         ------
         InvalidArgument
             Bad image format passed to ``format`` or invalid ``size``.
+
+        Returns
+        --------
+        :class:`str`
+            The resulting CDN URL.
         """
         if self.avatar is None:
             # Default is always blurple apparently
@@ -593,9 +593,9 @@ class Webhook:
 
         Parameters
         -------------
-        name: Optional[str]
+        name: Optional[:class:`str`]
             The webhook's new default name.
-        avatar: Optional[bytes]
+        avatar: Optional[:class:`bytes`]
             A :term:`py:bytes-like object` representing the webhook's new default avatar.
 
         Raises
@@ -651,19 +651,19 @@ class Webhook:
 
         Parameters
         ------------
-        content
+        content: :class:`str`
             The content of the message to send.
-        wait: bool
+        wait: :class:`bool`
             Whether the server should wait before sending a response. This essentially
             means that the return type of this function changes from ``None`` to
             a :class:`Message` if set to ``True``.
-        username: str
+        username: :class:`str`
             The username to send with this message. If no username is provided
             then the default username for the webhook is used.
-        avatar_url: str
+        avatar_url: :class:`str`
             The avatar URL to send with this message. If no avatar URL is provided
             then the default avatar for the webhook is used.
-        tts: bool
+        tts: :class:`bool`
             Indicates if the message should be sent using text-to-speech.
         file: :class:`File`
             The file to upload. This cannot be mixed with ``files`` parameter.

docs/api.rst

@@ -140,12 +140,12 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     printed to stderr and the exception is ignored. If you want to
     change this behaviour and handle the exception for whatever reason
     yourself, this event can be overridden. Which, when done, will
-    supress the default action of printing the traceback.
+    suppress the default action of printing the traceback.
 
-    The information of the exception rasied and the exception itself can
+    The information of the exception raised and the exception itself can
-    be retreived with a standard call to ``sys.exc_info()``.
+    be retrieved with a standard call to ``sys.exc_info()``.
 
-    If you want exception to propogate out of the :class:`Client` class
+    If you want exception to propagate out of the :class:`Client` class
     you can define an ``on_error`` handler consisting of a single empty
     ``raise`` statement.  Exceptions raised by ``on_error`` will not be
     handled in any way by :class:`Client`.
@@ -154,7 +154,7 @@ to handle it, which defaults to print a traceback and ignoring the exception.
     :param args: The positional arguments for the event that raised the
         exception.
     :param kwargs: The keyword arguments for the event that raised the
-        execption.
+        exception.
 
 .. function:: on_socket_raw_receive(msg)