Add standalone guide to enable debug logs.

Pointing to this information is frequently needed in the issue tracker.

Author: aaugustin

docs/faq/common.rst

@@ -3,33 +3,6 @@ Both sides
 
 .. currentmodule:: websockets.asyncio.connection
 
-.. _enable-debug-logs:
-
-How do I enable debug logs?
----------------------------
-
-You can enable debug logs to see exactly what websockets is doing.
-
-If logging isn't configured in your application::
-
- import logging
-
- logging.basicConfig(
- format="%(asctime)s %(message)s",
- level=logging.DEBUG,
- )
-
-If logging is already configured::
-
- import logging
-
- logger = logging.getLogger("websockets")
- logger.setLevel(logging.DEBUG)
- logger.addHandler(logging.StreamHandler())
-
-Refer to the :doc:`logging documentation <../topics/logging>` for more details
-on logging in websockets.
-
 What does ``ConnectionClosedError: no close frame received or sent`` mean?
 --------------------------------------------------------------------------
 
@@ -66,9 +39,8 @@ There are several reasons why long-lived connections may be lost:
  connections may terminate connections after a short amount of time, usually
  30 seconds, despite websockets' keepalive mechanism.
 
-If you're facing a reproducible issue, :ref:`enable debug logs
-<enable-debug-logs>` to see when and how connections are closed. connections are
-closed.
+If you're facing a reproducible issue, :doc:`enable debug logs
+<../howto/debugging>` to see when and how connections are closed.
 
 What does ``ConnectionClosedError: sent 1011 (internal error) keepalive ping timeout; no close frame received`` mean?
 ---------------------------------------------------------------------------------------------------------------------

docs/howto/autoreload.rst

@@ -7,8 +7,7 @@ stop the server and restart it, which slows down your development process.
 
 Web frameworks such as Django or Flask provide a development server that
 reloads the application automatically when you make code changes. There is no
-such functionality in websockets because it's designed for production rather
-than development.
+such functionality in websockets because it's designed only for production.
 
 However, you can achieve the same result easily.
 
@@ -27,5 +26,5 @@ Run your server with ``watchmedo auto-restart``:
  $ watchmedo auto-restart --pattern "*.py" --recursive --signal SIGTERM \
  python app.py
 
-This example assumes that the server is defined in a script called ``app.py``.
-Adapt it as necessary.
+This example assumes that the server is defined in a script called ``app.py``
+and exits cleanly when receiving the ``SIGTERM`` signal. Adapt it as necessary.

docs/howto/debugging.rst

@@ -0,0 +1,33 @@
+Enable debug logs
+==================
+
+websockets logs events with the :mod:`logging` module from the standard library.
+
+It writes to the ``"websockets.server"`` and ``"websockets.client"`` loggers.
+
+Enable logs at the ``DEBUG`` level to see exactly what websockets is doing.
+
+If logging isn't configured in your application::
+
+ import logging
+
+ logging.basicConfig(
+ format="%(asctime)s %(message)s",
+ level=logging.DEBUG,
+ )
+
+If logging is already configured::
+
+ import logging
+
+ logger = logging.getLogger("websockets")
+ logger.setLevel(logging.DEBUG)
+ logger.addHandler(logging.StreamHandler())
+
+Refer to the :doc:`logging guide <../topics/logging>` for more details on
+logging in websockets.
+
+In addition, you may enable asyncio's `debug mode`_ to see what asyncio is
+doing.
+
+.. _debug mode: https://docs.python.org/3/library/asyncio-dev.html#asyncio-debug-mode

docs/howto/index.rst

@@ -4,40 +4,30 @@ How-to guides
 In a hurry? Check out these examples.
 
 .. toctree::
- :titlesonly:
 
  quickstart
-
-Upgrading from the legacy :mod:`asyncio` implementation to the new one?
-Read this.
-
-.. toctree::
- :titlesonly:
-
- upgrade
+ debugging
+ autoreload
 
 If you're stuck, perhaps you'll find the answer here.
 
 .. toctree::
- :titlesonly:
 
  patterns
- autoreload
 
 This guide will help you integrate websockets into a broader system.
 
 .. toctree::
- :titlesonly:
 
  django
 
-The WebSocket protocol makes provisions for extending or specializing its
-features, which websockets supports fully.
+Upgrading from the legacy :mod:`asyncio` implementation to the new one?
+Read this.
 
 .. toctree::
- :titlesonly:
+ :maxdepth: 2
 
- extensions
+ upgrade
 
 If you're integrating the Sans-I/O layer of websockets into a library, rather
 than building an application with websockets, follow this guide.
@@ -46,3 +36,10 @@ than building an application with websockets, follow this guide.
  :maxdepth: 2
 
  sansio
+
+The WebSocket protocol makes provisions for extending or specializing its
+features, which websockets supports fully.
+
+.. toctree::
+
+ extensions

docs/intro/tutorial1.rst

@@ -545,7 +545,10 @@ taking alternate turns.
 
  import logging
 
- logging.basicConfig(format="%(message)s", level=logging.DEBUG)
+ logging.basicConfig(
+ format="%(asctime)s %(message)s",
+ level=logging.DEBUG,
+ )
 
 If you're stuck, a solution is available at the bottom of this document.