Add default logging configuration when using Client.run

While it is possible to do this type of your set up yourself, it's
better for beginners to have logging automatically set up for them.
This has come up often in the help channel over the years. This also
provides an escape hatch to disable it.

docs/logging.rst

@@ -1,5 +1,6 @@
 :orphan:
 
+.. currentmodule:: discord
 .. versionadded:: 0.6.0
 .. _logging_setup:
 
@@ -7,40 +8,71 @@ Setting Up Logging
 ===================
 
 *discord.py* logs errors and debug information via the :mod:`logging` python
-module. It is strongly recommended that the logging module is
-configured, as no errors or warnings will be output if it is not set up.
-Configuration of the ``logging`` module can be as simple as::
+module. In order to streamline this process, the library provides default configuration for the ``discord`` logger when using :meth:`Client.run`. It is strongly recommended that the logging module is configured, as no errors or warnings will be output if it is not set up.
+
+The default logging configuration provided by the library will print to :data:`sys.stderr` using coloured output. You can configure it to send to a file instead by using one of the built-in :mod:`logging.handlers`, such as :class:`logging.FileHandler`.
+
+This can be done by passing it through :meth:`Client.run`:
+
+.. code-block:: python3
 
     import logging
 
-    logging.basicConfig(level=logging.INFO)
+    handler = logging.FileHandler(filename='discord.log', encoding='utf-8', mode='w')
 
-Placed at the start of the application. This will output the logs from
-discord as well as other libraries that use the ``logging`` module
-directly to the console.
+    # Assume client refers to a discord.Client subclass...
+    client.run(token, log_handler=handler)
 
-The optional ``level`` argument specifies what level of events to log
-out and can be any of ``CRITICAL``, ``ERROR``, ``WARNING``, ``INFO``, and
-``DEBUG`` and if not specified defaults to ``WARNING``.
+You can also disable the library's logging configuration completely by passing ``None``:
 
-More advanced setups are possible with the :mod:`logging` module. For
-example to write the logs to a file called ``discord.log`` instead of
-outputting them to the console the following snippet can be used::
+.. code-block:: python3
+
+    client.run(token, log_handler=None)
+
+
+Likewise, configuring the log level to ``logging.DEBUG`` is also possible:
+
+.. code-block:: python3
+
+    import logging
+
+    handler = handler = logging.FileHandler(filename='discord.log', encoding='utf-8', mode='w')
+
+    # Assume client refers to a discord.Client subclass...
+    client.run(token, log_handler=handler, log_level=logging.DEBUG)
+
+This is recommended, especially at verbose levels such as ``DEBUG``, as there are a lot of events logged and it would clog the stderr of your program.
+
+More advanced setups are possible with the :mod:`logging` module. The example below configures a rotating file handler that outputs DEBUG output for everything the library outputs, except for HTTP requests:
+
+.. code-block:: python3
 
     import discord
     import logging
 
     logger = logging.getLogger('discord')
     logger.setLevel(logging.DEBUG)
-    handler = logging.FileHandler(filename='discord.log', encoding='utf-8', mode='w')
-    handler.setFormatter(logging.Formatter('%(asctime)s:%(levelname)s:%(name)s: %(message)s'))
+    logging.getLogger('discord.http').setLevel(logging.INFO)
+
+    handler = logging.RotatingFileHandler(
+        filename='discord.log',
+        encoding='utf-8',
+        maxBytes=32 * 1024 * 1024,  # 32 MiB
+        backupCount=5,  # Rotate through 5 files
+    )
+    formatter = logging.Formatter()
+    dt_fmt = '%Y-%m-%d %H:%M:%S'
+    formatter = logging.Formatter('[{asctime}] [{levelname:<8}] {name}: {message}', dt_fmt, style='{')
+    handler.setFormatter(formatter)
     logger.addHandler(handler)
 
-This is recommended, especially at verbose levels such as ``INFO``
-and ``DEBUG``, as there are a lot of events logged and it would clog the
-stdout of your program.
+    # Assume client refers to a discord.Client subclass...
+    # Suppress the default configuration since we have our own
+    client.run(token, log_handler=None)
 
 
+For more information, check the documentation and tutorial of the :mod:`logging` module.
 
-For more information, check the documentation and tutorial of the
-:mod:`logging` module.
+.. versionchanged:: 2.0
+
+    The library now provides a default logging configuration.