First pass at documentation reform.

6 files changed, 265 insertions, 165 deletions

diff --git a/discord/ext/commands/bot.py b/discord/ext/commands/bot.py
index 3bf4462a..886f9086 100644
--- a/discord/ext/commands/bot.py
+++ b/discord/ext/commands/bot.py
@@ -55,7 +55,7 @@ def when_mentioned_or(*prefixes):
 
     See Also
     ----------
-    :func:`when_mentioned`
+    :func:`.when_mentioned`
     """
     def inner(bot, msg):
         r = list(prefixes)
@@ -212,17 +212,17 @@ class BotBase(GroupMixin):
     def check(self, func):
         """A decorator that adds a global check to the bot.
 
-        A global check is similar to a :func:`check` that is applied
+        A global check is similar to a :func:`.check` that is applied
         on a per command basis except it is run before any command checks
         have been verified and applies to every command the bot has.
 
-        .. info::
+        .. note::
 
             This function can either be a regular function or a coroutine.
 
-        Similar to a command :func:`check`\, this takes a single parameter
-        of type :class:`Context` and can only raise exceptions derived from
-        :exc:`CommandError`.
+        Similar to a command :func:`.check`\, this takes a single parameter
+        of type :class:`.Context` and can only raise exceptions derived from
+        :exc:`.CommandError`.
 
         Example
         ---------
@@ -240,7 +240,7 @@ class BotBase(GroupMixin):
     def add_check(self, func):
         """Adds a global check to the bot.
 
-        This is the non-decorator interface to :meth:`check`.
+        This is the non-decorator interface to :meth:`.check`.
 
         Parameters
         -----------
@@ -275,15 +275,15 @@ class BotBase(GroupMixin):
 
     @asyncio.coroutine
     def is_owner(self, user):
-        """Checks if a :class:`User` or :class:`Member` is the owner of
+        """Checks if a :class:`.User` or :class:`.Member` is the owner of
         this bot.
 
         If an :attr:`owner_id` is not set, it is fetched automatically
-        through the use of :meth:`application_info`.
+        through the use of :meth:`~.Bot.application_info`.
 
         Parameters
         -----------
-        user: :class:`abc.User`
+        user: :class:`.abc.User`
             The user to check for.
         """
 
@@ -300,11 +300,11 @@ class BotBase(GroupMixin):
         called. This makes it a useful function to set up database
         connections or any type of set up required.
 
-        This pre-invoke hook takes a sole parameter, a :class:`Context`.
+        This pre-invoke hook takes a sole parameter, a :class:`.Context`.
 
         .. note::
 
-            The :meth:`before_invoke` and :meth:`after_invoke` hooks are
+            The :meth:`~.Bot.before_invoke` and :meth:`~.Bot.after_invoke` hooks are
             only called if all checks and argument parsing procedures pass
             without error. If any check or argument parsing procedures fail
             then the hooks are not called.
@@ -316,7 +316,7 @@ class BotBase(GroupMixin):
 
         Raises
         -------
-        discord.ClientException
+        :exc:`.ClientException`
             The coroutine is not actually a coroutine.
         """
         if not asyncio.iscoroutinefunction(coro):
@@ -332,14 +332,14 @@ class BotBase(GroupMixin):
         called. This makes it a useful function to clean-up database
         connections or any type of clean up required.
 
-        This post-invoke hook takes a sole parameter, a :class:`Context`.
+        This post-invoke hook takes a sole parameter, a :class:`.Context`.
 
         .. note::
 
-            Similar to :meth:`before_invoke`\, this is not called unless
+            Similar to :meth:`~.Bot.before_invoke`\, this is not called unless
             checks and argument parsing procedures succeed. This hook is,
             however, **always** called regardless of the internal command
-            callback raising an error (i.e. :exc:`CommandInvokeError`\).
+            callback raising an error (i.e. :exc:`.CommandInvokeError`\).
             This makes it ideal for clean-up scenarios.
 
         Parameters
@@ -349,7 +349,7 @@ class BotBase(GroupMixin):
 
         Raises
         -------
-        discord.ClientException
+        :exc:`.ClientException`
             The coroutine is not actually a coroutine.
         """
         if not asyncio.iscoroutinefunction(coro):
@@ -361,7 +361,7 @@ class BotBase(GroupMixin):
     # listener registration
 
     def add_listener(self, func, name=None):
-        """The non decorator alternative to :meth:`listen`.
+        """The non decorator alternative to :meth:`.listen`.
 
         Parameters
         -----------
@@ -415,7 +415,7 @@ class BotBase(GroupMixin):
     def listen(self, name=None):
         """A decorator that registers another function as an external
         event listener. Basically this allows you to listen to multiple
-        events from different places e.g. such as :func:`discord.on_ready`
+        events from different places e.g. such as :func:`.on_ready`
 
         The functions being listened to must be a coroutine.
 
@@ -438,7 +438,7 @@ class BotBase(GroupMixin):
 
         Raises
         -------
-        discord.ClientException
+        :exc:`.ClientException`
             The function being listened to is not a coroutine.
         """
 
@@ -459,7 +459,7 @@ class BotBase(GroupMixin):
         into a singular class that shares some state or no state at all.
 
         The cog can also have a ``__global_check`` member function that allows
-        you to define a global check. See :meth:`check` for more info.
+        you to define a global check. See :meth:`.check` for more info.
 
         More information will be documented soon.
 
@@ -515,7 +515,7 @@ class BotBase(GroupMixin):
 
         Returns
         ---------
-        Set[:class:`Command`]
+        Set[:class:`.Command`]
             A unique set of commands without aliases that belong
             to the cog.
         """
@@ -675,27 +675,27 @@ class BotBase(GroupMixin):
 
         Returns the invocation context from the message.
 
-        This is a more low-level counter-part for :meth:`process_message`
+        This is a more low-level counter-part for :meth:`.process_commands`
         to allow users more fine grained control over the processing.
 
         The returned context is not guaranteed to be a valid invocation
-        context, :attr:`Context.valid` must be checked to make sure it is.
+        context, :attr:`.Context.valid` must be checked to make sure it is.
         If the context is not valid then it is not a valid candidate to be
-        invoked under :meth:`invoke`.
+        invoked under :meth:`~.Bot.invoke`.
 
         Parameters
         -----------
         message: :class:`discord.Message`
             The message to get the invocation context from.
-        cls: type
+        cls
             The factory class that will be used to create the context.
-            By default, this is :class:`Context`. Should a custom
-            class be provided, it must be similar enough to :class:`Context`\'s
+            By default, this is :class:`.Context`. Should a custom
+            class be provided, it must be similar enough to :class:`.Context`\'s
             interface.
 
         Returns
         --------
-        :class:`Context`
+        :class:`.Context`
             The invocation context. The type of this can change via the
             ``cls`` parameter.
         """
@@ -732,7 +732,7 @@ class BotBase(GroupMixin):
 
         Parameters
         -----------
-        ctx: :class:`Context`
+        ctx: :class:`.Context`
             The invocation context to invoke.
         """
         if ctx.command is not None:
@@ -756,12 +756,12 @@ class BotBase(GroupMixin):
         to the bot and other groups. Without this coroutine, none of the
         commands will be triggered.
 
-        By default, this coroutine is called inside the :func:`on_message`
-        event. If you choose to override the :func:`on_message` event, then
+        By default, this coroutine is called inside the :func:`.on_message`
+        event. If you choose to override the :func:`.on_message` event, then
         you should invoke this coroutine as well.
 
         This is built using other low level tools, and is equivalent to a
-        call to :meth:`get_context` followed by a call to :meth:`invoke`.
+        call to :meth:`~.Bot.get_context` followed by a call to :meth:`~.Bot.invoke`.
 
         Parameters
         -----------
@@ -782,7 +782,10 @@ class Bot(BotBase, discord.Client):
     anything that you can do with a :class:`discord.Client` you can do with
     this bot.
 
-    This class also subclasses :class:`GroupMixin` to provide the functionality
+    .. _deque: https://docs.python.org/3.4/library/collections.html#collections.deque
+    .. _event loop: https://docs.python.org/3/library/asyncio-eventloops.html
+
+    This class also subclasses :class:`.GroupMixin` to provide the functionality
     to manage commands.
 
     Attributes
@@ -799,18 +802,18 @@ class Bot(BotBase, discord.Client):
         The command prefix could also be a list or a tuple indicating that
         multiple checks for the prefix should be used and the first one to
         match will be the invocation prefix. You can get this prefix via
-        :attr:`Context.prefix`.
+        :attr:`.Context.prefix`.
     description : str
         The content prefixed into the default help message.
     self_bot : bool
         If ``True``, the bot will only listen to commands invoked by itself rather
         than ignoring itself. If ``False`` (the default) then the bot will ignore
         itself. This cannot be changed once initialised.
-    formatter : :class:`HelpFormatter`
+    formatter : :class:`.HelpFormatter`
         The formatter used to format the help message. By default, it uses a
-        the :class:`HelpFormatter`. Check it for more info on how to override it.
+        the :class:`.HelpFormatter`. Check it for more info on how to override it.
         If you want to change the help command completely (add aliases, etc) then
-        a call to :meth:`remove_command` with 'help' as the argument would do the
+        a call to :meth:`~.Bot.remove_command` with 'help' as the argument would do the
         trick.
     pm_help : Optional[bool]
         A tribool that indicates if the help command should PM the user instead of
@@ -823,7 +826,7 @@ class Bot(BotBase, discord.Client):
         A dictionary of options to pass in for the construction of the help command.
         This allows you to change the command behaviour without actually changing
         the implementation of the command. The attributes will be the same as the
-        ones passed in the :class:`Command` constructor. Note that ``pass_context``
+        ones passed in the :class:`.Command` constructor. Note that ``pass_context``
         will always be set to ``True`` regardless of what you pass in.
     command_not_found : str
         The format string used when the help command is invoked with a command that
@@ -833,16 +836,16 @@ class Bot(BotBase, discord.Client):
         The format string used when the help command is invoked with requests for a
         subcommand but the command does not have any subcommands. Defaults to
         ``"Command {0.name} has no subcommands."``. The first format argument is the
-        :class:`Command` attempted to get a subcommand and the second is the name.
+        :class:`.Command` attempted to get a subcommand and the second is the name.
     owner_id: Optional[int]
         The ID that owns the bot. If this is not set and is then queried via
-        :meth:`is_owner` then it is fetched automatically using
-        :meth:`application_info`.
+        :meth:`.is_owner` then it is fetched automatically using
+        :meth:`~.Bot.application_info`.
     """
     pass
 
 class AutoShardedBot(BotBase, discord.AutoShardedClient):
-    """This is similar to :class:`Bot` except that it is derived from
+    """This is similar to :class:`.Bot` except that it is derived from
     :class:`discord.AutoShardedClient` instead.
     """
     pass
diff --git a/discord/ext/commands/context.py b/discord/ext/commands/context.py
index f07ab6ac..2d5ec2da 100644
--- a/discord/ext/commands/context.py
+++ b/discord/ext/commands/context.py
@@ -40,7 +40,7 @@ class Context(discord.abc.Messageable):
     -----------
     message: :class:`discord.Message`
         The message that triggered the command being executed.
-    bot: :class:`Bot`
+    bot: :class:`.Bot`
         The bot that contains the command being executed.
     args: list
         The list of transformed arguments that were passed into the command.
@@ -53,13 +53,13 @@ class Context(discord.abc.Messageable):
     prefix: str
         The prefix that was used to invoke the command.
     command
-        The command (i.e. :class:`Command` or its superclasses) that is being
+        The command (i.e. :class:`.Command` or its superclasses) that is being
         invoked currently.
     invoked_with: str
         The command name that triggered this invocation. Useful for finding out
         which alias called the command.
     invoked_subcommand
-        The subcommand (i.e. :class:`Command` or its superclasses) that was
+        The subcommand (i.e. :class:`.Command` or its superclasses) that was
         invoked. If no valid subcommand was invoked then this is equal to
         `None`.
     subcommand_passed: Optional[str]
@@ -93,7 +93,7 @@ class Context(discord.abc.Messageable):
         Calls a command with the arguments given.
 
         This is useful if you want to just call the callback that a
-        :class:`Command` holds internally.
+        :class:`.Command` holds internally.
 
         Note
         ------
@@ -101,7 +101,7 @@ class Context(discord.abc.Messageable):
 
         Parameters
         -----------
-        command : :class:`Command`
+        command : :class:`.Command`
             A command or superclass of a command that is going to be called.
         \*args
             The arguments to to use.
diff --git a/discord/ext/commands/converter.py b/discord/ext/commands/converter.py
index 36e53fd2..4bd2fd74 100644
--- a/discord/ext/commands/converter.py
+++ b/discord/ext/commands/converter.py
@@ -46,14 +46,14 @@ def _get_from_guilds(bot, getter, argument):
     return result
 
 class Converter:
-    """The base class of custom converters that require the :class:`Context`
+    """The base class of custom converters that require the :class:`.Context`
     to be passed to be useful.
 
     This allows you to implement converters that function similar to the
     special cased ``discord`` classes.
 
-    Classes that derive from this should override the :meth:`convert` method
-    to do its conversion logic. This method must be a coroutine.
+    Classes that derive from this should override the :meth:`~.Converter.convert`
+    method to do its conversion logic. This method must be a coroutine.
     """
 
     @asyncio.coroutine
@@ -62,15 +62,13 @@ class Converter:
 
         The method to override to do conversion logic.
 
-        This can either be a coroutine or a regular function.
-
         If an error is found while converting, it is recommended to
-        raise a :class:`CommandError` derived exception as it will
+        raise a :exc:`.CommandError` derived exception as it will
         properly propagate to the error handlers.
 
         Parameters
         -----------
-        ctx: :class:`Context`
+        ctx: :class:`.Context`
             The invocation context that the argument is being used in.
         argument: str
             The argument that is being converted.
@@ -86,6 +84,20 @@ class IDConverter(Converter):
         return self._id_regex.match(argument)
 
 class MemberConverter(IDConverter):
+    """Converts to a :class:`Member`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name#discrim
+    4. Lookup by name
+    5. Lookup by nickname
+    """
+
     @asyncio.coroutine
     def convert(self, ctx, argument):
         message = ctx.message
@@ -112,6 +124,17 @@ class MemberConverter(IDConverter):
         return result
 
 class UserConverter(IDConverter):
+    """Converts to a :class:`User`.
+
+    All lookups are via the global user cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name#discrim
+    4. Lookup by name
+    """
     @asyncio.coroutine
     def convert(self, ctx, argument):
         match = self._get_id_match(argument) or re.match(r'<@!?([0-9]+)>$', argument)
@@ -141,6 +164,17 @@ class UserConverter(IDConverter):
         return result
 
 class TextChannelConverter(IDConverter):
+    """Converts to a :class:`TextChannel`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name
+    """
     @asyncio.coroutine
     def convert(self, ctx, argument):
         bot = ctx.bot
@@ -170,6 +204,17 @@ class TextChannelConverter(IDConverter):
         return result
 
 class VoiceChannelConverter(IDConverter):
+    """Converts to a :class:`VoiceChannel`.
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name
+    """
     @asyncio.coroutine
     def convert(self, ctx, argument):
         bot = ctx.bot
@@ -198,6 +243,17 @@ class VoiceChannelConverter(IDConverter):
         return result
 
 class ColourConverter(Converter):
+    """Converts to a :class:`Colour`.
+
+    The following formats are accepted:
+
+    - ``0x<hex>``
+    - ``#<hex>``
+    - ``0x#<hex>``
+    - Any of the ``classmethod`` in :class:`Colour`
+
+        - The ``_`` in the name can be optionally replaced with spaces.
+    """
     @asyncio.coroutine
     def convert(self, ctx, argument):
         arg = argument.replace('0x', '').lower()
@@ -208,12 +264,24 @@ class ColourConverter(Converter):
             value = int(arg, base=16)
             return discord.Colour(value=value)
         except ValueError:
-            method = getattr(discord.Colour, arg, None)
+            method = getattr(discord.Colour, arg.replace(' ', '_'), None)
             if method is None or not inspect.ismethod(method):
                 raise BadArgument('Colour "{}" is invalid.'.format(arg))
             return method()
 
 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.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by mention.
+    3. Lookup by name
+    """
     @asyncio.coroutine
     def convert(self, ctx, argument):
         guild = ctx.message.guild
@@ -228,11 +296,16 @@ class RoleConverter(IDConverter):
         return result
 
 class GameConverter(Converter):
+    """Converts to :class:`Game`."""
     @asyncio.coroutine
     def convert(self, ctx, argument):
         return discord.Game(name=argument)
 
 class InviteConverter(Converter):
+    """Converts to a :class:`Invite`.
+
+    This is done via an HTTP request using :meth:`.Bot.get_invite`.
+    """
     @asyncio.coroutine
     def convert(self, ctx, argument):
         try:
@@ -242,6 +315,18 @@ class InviteConverter(Converter):
             raise BadArgument('Invite is invalid or expired') from e
 
 class EmojiConverter(IDConverter):
+    """Converts to a :class:`Emoji`.
+
+
+    All lookups are via the local guild. If in a DM context, then the lookup
+    is done by the global cache.
+
+    The lookup strategy is as follows (in order):
+
+    1. Lookup by ID.
+    2. Lookup by extracting ID from the emoji.
+    3. Lookup by name
+    """
     @asyncio.coroutine
     def convert(self, ctx, argument):
         match = self._get_id_match(argument) or re.match(r'<:[a-zA-Z0-9]+:([0-9]+)>$', argument)
@@ -272,6 +357,18 @@ class EmojiConverter(IDConverter):
         return result
 
 class clean_content(Converter):
+    """Converts the argument to mention scrubbed version of
+    said content.
+
+    This behaves similarly to :attr:`.Message.clean_content`.
+
+    Attributes
+    ------------
+    fix_channel_mentions: bool
+        Whether to clean channel mentions.
+    use_nicknames: bool
+        Whether to use nicknames when transforming mentions.
+    """
     def __init__(self, *, fix_channel_mentions=False, use_nicknames=True):
         self.fix_channel_mentions = fix_channel_mentions
         self.use_nicknames = use_nicknames
diff --git a/discord/ext/commands/core.py b/discord/ext/commands/core.py
index 0b05a1ae..17925f59 100644
--- a/discord/ext/commands/core.py
+++ b/discord/ext/commands/core.py
@@ -88,54 +88,54 @@ class Command:
 
     Attributes
     -----------
-    name : str
+    name: str
         The name of the command.
-    callback : coroutine
+    callback: coroutine
         The coroutine that is executed when the command is called.
-    help : str
+    help: str
         The long help text for the command.
-    brief : str
+    brief: str
         The short help text for the command. If this is not specified
         then the first line of the long help text is used instead.
-    usage : str
+    usage: str
         A replacement for arguments in the default help text.
-    aliases : list
+    aliases: list
         The list of aliases the command can be invoked under.
-    pass_context : bool
-        A boolean that indicates that the current :class:`Context` should
+    pass_context: bool
+        A boolean that indicates that the current :class:`.Context` should
         be passed as the **first parameter**. Defaults to `True`.
-    enabled : bool
+    enabled: bool
         A boolean that indicates if the command is currently enabled.
         If the command is invoked while it is disabled, then
-        :exc:`DisabledCommand` is raised to the :func:`on_command_error`
+        :exc:`.DisabledCommand` is raised to the :func:`.on_command_error`
         event. Defaults to ``True``.
-    parent : Optional[command]
+    parent: Optional[command]
         The parent command that this command belongs to. ``None`` is there
         isn't one.
     checks
         A list of predicates that verifies if the command could be executed
-        with the given :class:`Context` as the sole parameter. If an exception
+        with the given :class:`.Context` as the sole parameter. If an exception
         is necessary to be thrown to signal failure, then one derived from
-        :exc:`CommandError` should be used. Note that if the checks fail then
-        :exc:`CheckFailure` exception is raised to the :func:`on_command_error`
+        :exc:`.CommandError` should be used. Note that if the checks fail then
+        :exc:`.CheckFailure` exception is raised to the :func:`.on_command_error`
         event.
-    description : str
+    description: str
         The message prefixed into the default help command.
-    hidden : bool
+    hidden: bool
         If ``True``\, the default help command does not show this in the
         help output.
-    rest_is_raw : bool
+    rest_is_raw: bool
         If ``False`` and a keyword-only argument is provided then the keyword
         only argument is stripped and handled as if it was a regular argument
-        that handles :exc:`MissingRequiredArgument` and default values in a
+        that handles :exc:`.MissingRequiredArgument` and default values in a
         regular matter rather than passing the rest completely raw. If ``True``
         then the keyword-only argument will pass in the rest of the arguments
         in a completely raw matter. Defaults to ``False``.
-    ignore_extra : bool
+    ignore_extra: bool
         If ``True``\, ignores extraneous strings passed to a command if all its
         requirements are met (e.g. ``?foo a b c`` when only expecting ``a``
-        and ``b``). Otherwise :func:`on_command_error` and local error handlers
-        are called with :exc:`TooManyArguments`. Defaults to ``True``.
+        and ``b``). Otherwise :func:`.on_command_error` and local error handlers
+        are called with :exc:`.TooManyArguments`. Defaults to ``True``.
     """
     def __init__(self, name, callback, **kwargs):
         self.name = name
@@ -418,7 +418,7 @@ class Command:
 
         Parameters
         -----------
-        ctx: :class:`Context`
+        ctx: :class:`.Context`
             The invocation context to reset the cooldown under.
         """
         if self._buckets.valid:
@@ -439,8 +439,8 @@ class Command:
     def error(self, coro):
         """A decorator that registers a coroutine as a local error handler.
 
-        A local error handler is an :func:`on_command_error` event limited to
-        a single command. However, the :func:`on_command_error` is still
+        A local error handler is an :func:`.on_command_error` event limited to
+        a single command. However, the :func:`.on_command_error` is still
         invoked afterwards as the catch-all.
 
         Parameters
@@ -463,13 +463,13 @@ class Command:
     def before_invoke(self, coro):
         """A decorator that registers a coroutine as a pre-invoke hook.
 
-        A pre-invoke hook is called directly before :meth:`invoke` is
+        A pre-invoke hook is called directly before the command is
         called. This makes it a useful function to set up database
         connections or any type of set up required.
 
-        This pre-invoke hook takes a sole parameter, a :class:`Context`.
+        This pre-invoke hook takes a sole parameter, a :class:`.Context`.
 
-        See :meth:`Bot.before_invoke` for more info.
+        See :meth:`.Bot.before_invoke` for more info.
 
         Parameters
         -----------
@@ -478,7 +478,7 @@ class Command:
 
         Raises
         -------
-        discord.ClientException
+        :exc:`.ClientException`
             The coroutine is not actually a coroutine.
         """
         if not asyncio.iscoroutinefunction(coro):
@@ -490,13 +490,13 @@ class Command:
     def after_invoke(self, coro):
         """A decorator that registers a coroutine as a post-invoke hook.
 
-        A post-invoke hook is called directly after :meth:`invoke` is
+        A post-invoke hook is called directly after the command is
         called. This makes it a useful function to clean-up database
         connections or any type of clean up required.
 
-        This post-invoke hook takes a sole parameter, a :class:`Context`.
+        This post-invoke hook takes a sole parameter, a :class:`.Context`.
 
-        See :meth:`Bot.after_invoke` for more info.
+        See :meth:`.Bot.after_invoke` for more info.
 
         Parameters
         -----------
@@ -505,7 +505,7 @@ class Command:
 
         Raises
         -------
-        discord.ClientException
+        :exc:`.ClientException`
             The coroutine is not actually a coroutine.
         """
         if not asyncio.iscoroutinefunction(coro):
@@ -577,11 +577,11 @@ class Command:
         """|coro|
 
         Checks if the command can be executed by checking all the predicates
-        inside the :attr:`checks` attribute.
+        inside the :attr:`.checks` attribute.
 
         Parameters
         -----------
-        ctx: :class:`Context`
+        ctx: :class:`.Context`
             The ctx of the command currently being invoked.
 
         Returns
@@ -613,12 +613,12 @@ class Command:
 
 class GroupMixin:
     """A mixin that implements common functionality for classes that behave
-    similar to :class:`Group` and are allowed to register commands.
+    similar to :class:`.Group` and are allowed to register commands.
 
     Attributes
     -----------
     all_commands: dict
-        A mapping of command name to :class:`Command` or superclass
+        A mapping of command name to :class:`.Command` or superclass
         objects.
     """
     def __init__(self, **kwargs):
@@ -627,7 +627,7 @@ class GroupMixin:
 
     @property
     def commands(self):
-        """Set[:class:`Command`]: A unique set of commands without aliases that are registered."""
+        """Set[:class:`.Command`]: A unique set of commands without aliases that are registered."""
         return set(self.all_commands.values())
 
     def recursively_remove_all_commands(self):
@@ -637,11 +637,11 @@ class GroupMixin:
             self.remove_command(command.name)
 
     def add_command(self, command):
-        """Adds a :class:`Command` or its superclasses into the internal list
+        """Adds a :class:`.Command` or its superclasses into the internal list
         of commands.
 
-        This is usually not called, instead the :meth:`command` or
-        :meth:`group` shortcut decorators are used instead.
+        This is usually not called, instead the :meth:`~.GroupMixin.command` or
+        :meth:`~.GroupMixin.group` shortcut decorators are used instead.
 
         Parameters
         -----------
@@ -650,10 +650,10 @@ class GroupMixin:
 
         Raises
         -------
-        discord.ClientException
+        :exc:`.ClientException`
             If the command is already registered.
         TypeError
-            If the command passed is not a subclass of :class:`Command`.
+            If the command passed is not a subclass of :class:`.Command`.
         """
 
         if not isinstance(command, Command):
@@ -672,19 +672,19 @@ class GroupMixin:
             self.all_commands[alias] = command
 
     def remove_command(self, name):
-        """Remove a :class:`Command` or subclasses from the internal list
+        """Remove a :class:`.Command` or subclasses from the internal list
         of commands.
 
         This could also be used as a way to remove aliases.
 
         Parameters
         -----------
-        name : str
+        name: str
             The name of the command to remove.
 
         Returns
         --------
-        Command or subclass
+        :class:`.Command` or subclass
             The command that was removed. If the name is not valid then
             `None` is returned instead.
         """
@@ -711,7 +711,7 @@ class GroupMixin:
                 yield from command.walk_commands()
 
     def get_command(self, name):
-        """Get a :class:`Command` or subclasses from the internal list
+        """Get a :class:`.Command` or subclasses from the internal list
         of commands.
 
         This could also be used as a way to get aliases.
@@ -745,8 +745,8 @@ class GroupMixin:
         return obj
 
     def command(self, *args, **kwargs):
-        """A shortcut decorator that invokes :func:`command` and adds it to
-        the internal command list via :meth:`add_command`.
+        """A shortcut decorator that invokes :func:`.command` and adds it to
+        the internal command list via :meth:`~.GroupMixin.add_command`.
         """
         def decorator(func):
             result = command(*args, **kwargs)(func)
@@ -756,8 +756,8 @@ class GroupMixin:
         return decorator
 
     def group(self, *args, **kwargs):
-        """A shortcut decorator that invokes :func:`group` and adds it to
-        the internal command list via :meth:`add_command`.
+        """A shortcut decorator that invokes :func:`.group` and adds it to
+        the internal command list via :meth:`~.GroupMixin.add_command`.
         """
         def decorator(func):
             result = group(*args, **kwargs)(func)
@@ -770,12 +770,12 @@ class Group(GroupMixin, Command):
     """A class that implements a grouping protocol for commands to be
     executed as subcommands.
 
-    This class is a subclass of :class:`Command` and thus all options
-    valid in :class:`Command` are valid in here as well.
+    This class is a subclass of :class:`.Command` and thus all options
+    valid in :class:`.Command` are valid in here as well.
 
     Attributes
     -----------
-    invoke_without_command : bool
+    invoke_without_command: bool
         Indicates if the group callback should begin parsing and
         invocation only if no subcommand was found. Useful for
         making it an error handling function to tell the user that
@@ -820,25 +820,25 @@ class Group(GroupMixin, Command):
 # Decorators
 
 def command(name=None, cls=None, **attrs):
-    """A decorator that transforms a function into a :class:`Command`
-    or if called with :func:`group`, :class:`Group`.
+    """A decorator that transforms a function into a :class:`.Command`
+    or if called with :func:`.group`, :class:`.Group`.
 
     By default the ``help`` attribute is received automatically from the
     docstring of the function and is cleaned up with the use of
     ``inspect.cleandoc``. If the docstring is ``bytes``, then it is decoded
     into ``str`` using utf-8 encoding.
 
-    All checks added using the :func:`check` & co. decorators are added into
+    All checks added using the :func:`.check` & co. decorators are added into
     the function. There is no way to supply your own checks through this
     decorator.
 
     Parameters
     -----------
-    name : str
+    name: str
         The name to create the command with. By default this uses the
         function name unchanged.
     cls
-        The class to construct with. By default this is :class:`Command`.
+        The class to construct with. By default this is :class:`.Command`.
         You usually do not change this.
     attrs
         Keyword arguments to pass into the construction of the class denoted
@@ -886,28 +886,28 @@ def command(name=None, cls=None, **attrs):
     return decorator
 
 def group(name=None, **attrs):
-    """A decorator that transforms a function into a :class:`Group`.
+    """A decorator that transforms a function into a :class:`.Group`.
 
-    This is similar to the :func:`command` decorator but creates a
-    :class:`Group` instead of a :class:`Command`.
+    This is similar to the :func:`.command` decorator but creates a
+    :class:`.Group` instead of a :class:`.Command`.
     """
     return command(name=name, cls=Group, **attrs)
 
 def check(predicate):
-    """A decorator that adds a check to the :class:`Command` or its
-    subclasses. These checks could be accessed via :attr:`Command.checks`.
+    """A decorator that adds a check to the :class:`.Command` or its
+    subclasses. These checks could be accessed via :attr:`.Command.checks`.
 
     These checks should be predicates that take in a single parameter taking
-    a :class:`Context`. If the check returns a ``False``\-like value then
-    during invocation a :exc:`CheckFailure` exception is raised and sent to
-    the :func:`on_command_error` event.
+    a :class:`.Context`. If the check returns a ``False``\-like value then
+    during invocation a :exc:`.CheckFailure` exception is raised and sent to
+    the :func:`.on_command_error` event.
 
     If an exception should be thrown in the predicate then it should be a
-    subclass of :exc:`CommandError`. Any exception not subclassed from it
+    subclass of :exc:`.CommandError`. Any exception not subclassed from it
     will be propagated while those subclassed will be sent to
-    :func:`on_command_error`.
+    :func:`.on_command_error`.
 
-    .. info::
+    .. note::
 
         These functions can either be regular functions or coroutines.
 
@@ -960,7 +960,7 @@ def check(predicate):
     return decorator
 
 def has_role(name):
-    """A :func:`check` that is added that checks if the member invoking the
+    """A :func:`.check` that is added that checks if the member invoking the
     command has the role specified via the name specified.
 
     The name is case sensitive and must be exact. No normalisation is done in
@@ -971,7 +971,7 @@ def has_role(name):
 
     Parameters
     -----------
-    name : str
+    name: str
         The name of the role to check.
     """
 
@@ -985,11 +985,11 @@ def has_role(name):
     return check(predicate)
 
 def has_any_role(*names):
-    """A :func:`check` that is added that checks if the member invoking the
+    """A :func:`.check` that is added that checks if the member invoking the
     command has **any** of the roles specified. This means that if they have
     one out of the three roles specified, then this check will return `True`.
 
-    Similar to :func:`has_role`\, the names passed in must be exact.
+    Similar to :func:`.has_role`\, the names passed in must be exact.
 
     Parameters
     -----------
@@ -1015,11 +1015,11 @@ def has_any_role(*names):
     return check(predicate)
 
 def has_permissions(**perms):
-    """A :func:`check` that is added that checks if the member has any of
+    """A :func:`.check` that is added that checks if the member has any of
     the permissions necessary.
 
     The permissions passed in must be exactly like the properties shown under
-    :class:`discord.Permissions`.
+    :class:`.discord.Permissions`.
 
     Parameters
     ------------
@@ -1045,7 +1045,7 @@ def has_permissions(**perms):
     return check(predicate)
 
 def bot_has_role(name):
-    """Similar to :func:`has_role` except checks if the bot itself has the
+    """Similar to :func:`.has_role` except checks if the bot itself has the
     role.
     """
 
@@ -1059,7 +1059,7 @@ def bot_has_role(name):
     return check(predicate)
 
 def bot_has_any_role(*names):
-    """Similar to :func:`has_any_role` except checks if the bot itself has
+    """Similar to :func:`.has_any_role` except checks if the bot itself has
     any of the roles listed.
     """
     def predicate(ctx):
@@ -1072,7 +1072,7 @@ def bot_has_any_role(*names):
     return check(predicate)
 
 def bot_has_permissions(**perms):
-    """Similar to :func:`has_permissions` except checks if the bot itself has
+    """Similar to :func:`.has_permissions` except checks if the bot itself has
     the permissions listed.
     """
     def predicate(ctx):
@@ -1083,12 +1083,12 @@ def bot_has_permissions(**perms):
     return check(predicate)
 
 def guild_only():
-    """A :func:`check` that indicates this command must only be used in a
+    """A :func:`.check` that indicates this command must only be used in a
     guild context only. Basically, no private messages are allowed when
     using the command.
 
-    This check raises a special exception, :exc:`NoPrivateMessage`
-    that is derived from :exc:`CheckFailure`.
+    This check raises a special exception, :exc:`.NoPrivateMessage`
+    that is derived from :exc:`.CheckFailure`.
     """
 
     def predicate(ctx):
@@ -1099,13 +1099,13 @@ def guild_only():
     return check(predicate)
 
 def is_owner():
-    """A :func:`check` that checks if the person invoking this command is the
+    """A :func:`.check` that checks if the person invoking this command is the
     owner of the bot.
 
-    This is powered by :meth:`Bot.is_owner`.
+    This is powered by :meth:`.Bot.is_owner`.
 
-    This check raises a special exception, :exc:`NotOwner` that is derived
-    from :exc:`CheckFailure`.
+    This check raises a special exception, :exc:`.NotOwner` that is derived
+    from :exc:`.CheckFailure`.
     """
 
     @asyncio.coroutine
@@ -1117,13 +1117,13 @@ def is_owner():
     return check(predicate)
 
 def is_nsfw():
-    """A :func:`check` that checks if the channel is a NSFW channel."""
+    """A :func:`.check` that checks if the channel is a NSFW channel."""
     def pred(ctx):
         return isinstance(ctx.channel, discord.TextChannel) and ctx.channel.is_nsfw()
     return check(pred)
 
 def cooldown(rate, per, type=BucketType.default):
-    """A decorator that adds a cooldown to a :class:`Command`
+    """A decorator that adds a cooldown to a :class:`.Command`
     or its subclasses.
 
     A cooldown allows a command to only be used a specific amount
@@ -1137,8 +1137,8 @@ def cooldown(rate, per, type=BucketType.default):
     - ``BucketType.guild`` for a per-guild basis.
     - ``BucketType.channel`` for a per-channel basis.
 
-    If a cooldown is triggered, then :exc:`CommandOnCooldown` is triggered in
-    :func:`on_command_error` and the local error handler.
+    If a cooldown is triggered, then :exc:`.CommandOnCooldown` is triggered in
+    :func:`.on_command_error` and the local error handler.
 
     A command can only have a single cooldown.
 
diff --git a/discord/ext/commands/errors.py b/discord/ext/commands/errors.py
index 829fb011..555bfd99 100644
--- a/discord/ext/commands/errors.py
+++ b/discord/ext/commands/errors.py
@@ -38,7 +38,7 @@ class CommandError(DiscordException):
 
     This exception and exceptions derived from it are handled
     in a special way as they are caught and passed into a special event
-    from :class:`Bot`\, :func:`on_command_error`.
+    from :class:`.Bot`\, :func:`on_command_error`.
     """
     def __init__(self, message=None, *args):
         if message is not None:
@@ -52,7 +52,7 @@ class UserInputError(CommandError):
     """The base exception type for errors that involve errors
     regarding user input.
 
-    This inherits from :exc:`CommandError`.
+    This inherits from :exc:`.CommandError`.
     """
     pass
 
@@ -80,7 +80,7 @@ class MissingRequiredArgument(UserInputError):
 
 class TooManyArguments(UserInputError):
     """Exception raised when the command was passed too many arguments and its
-    :attr:`Command.ignore_extra` attribute was not set to ``True``.
+    :attr:`.Command.ignore_extra` attribute was not set to ``True``.
     """
     pass
 
@@ -91,7 +91,7 @@ class BadArgument(UserInputError):
     pass
 
 class CheckFailure(CommandError):
-    """Exception raised when the predicates in :attr:`Command.checks` have failed."""
+    """Exception raised when the predicates in :attr:`.Command.checks` have failed."""
     pass
 
 class NoPrivateMessage(CheckFailure):
@@ -128,7 +128,7 @@ class CommandOnCooldown(CommandError):
     -----------
     cooldown: Cooldown
         A class with attributes ``rate``, ``per``, and ``type`` similar to
-        the :func:`cooldown` decorator.
+        the :func:`.cooldown` decorator.
     retry_after: float
         The amount of seconds to wait before you can retry again.
     """
diff --git a/discord/ext/commands/formatter.py b/discord/ext/commands/formatter.py
index 523d616a..8e30f58d 100644
--- a/discord/ext/commands/formatter.py
+++ b/discord/ext/commands/formatter.py
@@ -127,19 +127,19 @@ class HelpFormatter:
     """The default base implementation that handles formatting of the help
     command.
 
-    To override the behaviour of the formatter, :meth:`format`
+    To override the behaviour of the formatter, :meth:`~.HelpFormatter.format`
     should be overridden. A number of utility functions are provided for use
     inside that method.
 
-    Parameters
+    Attributes
     -----------
-    show_hidden : bool
+    show_hidden: bool
         Dictates if hidden commands should be shown in the output.
         Defaults to ``False``.
-    show_check_failure : bool
-        Dictates if commands that have their :attr:`Command.checks` failed
+    show_check_failure: bool
+        Dictates if commands that have their :attr:`.Command.checks` failed
         shown. Defaults to ``False``.
-    width : int
+    width: int
         The maximum number of characters that fit in a line.
         Defaults to 80.
     """
@@ -149,15 +149,15 @@ class HelpFormatter:
         self.show_check_failure = show_check_failure
 
     def has_subcommands(self):
-        """bool : Specifies if the command has subcommands."""
+        """bool: Specifies if the command has subcommands."""
         return isinstance(self.command, GroupMixin)
 
     def is_bot(self):
-        """bool : Specifies if the command being formatted is the bot itself."""
+        """bool: Specifies if the command being formatted is the bot itself."""
         return self.command is self.context.bot
 
     def is_cog(self):
-        """bool : Specifies if the command being formatted is actually a cog."""
+        """bool: Specifies if the command being formatted is actually a cog."""
         return not self.is_bot() and not isinstance(self.command, Command)
 
     def shorten(self, text):
@@ -168,7 +168,7 @@ class HelpFormatter:
 
     @property
     def max_name_size(self):
-        """int : Returns the largest name length of a command or if it has subcommands
+        """int: Returns the largest name length of a command or if it has subcommands
         the largest subcommand name."""
         try:
             commands = self.command.all_commands if not self.is_cog() else self.context.bot.all_commands
@@ -202,8 +202,8 @@ class HelpFormatter:
     @asyncio.coroutine
     def filter_command_list(self):
         """Returns a filtered list of commands based on the two attributes
-        provided, :attr:`show_check_failure` and :attr:`show_hidden`. Also
-        filters based on if :meth:`is_cog` is valid.
+        provided, :attr:`show_check_failure` and :attr:`show_hidden`.
+        Also filters based on if :meth:`~.HelpFormatter.is_cog` is valid.
 
         Returns
         --------
@@ -262,13 +262,13 @@ class HelpFormatter:
     def format_help_for(self, context, command_or_bot):
         """Formats the help page and handles the actual heavy lifting of how
         the help command looks like. To change the behaviour, override the
-        :meth:`format` method.
+        :meth:`~.HelpFormatter.format` method.
 
         Parameters
         -----------
-        context : :class:`Context`
+        context: :class:`.Context`
             The context of the invoked help command.
-        command_or_bot : :class:`Command` or :class:`Bot`
+        command_or_bot: :class:`.Command` or :class:`.Bot`
             The bot or command that we are getting the help of.
 
         Returns