Add logging documentation

diff --git a/docs/index.rst b/docs/index.rst
index e4928e9094d3d0970d03ddba8580d7b77660f6c6..cd79f5abc1b6a6a9e0ec11aeeebe3ab569245a6a 100644 (file)
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -21,6 +21,7 @@ Contents:
    asyncstream.rst
    exceptions.rst
    extended_tweets.rst
+   logging.rst
    pagination.rst
    streaming.rst
    changelog.md

diff --git a/docs/logging.rst b/docs/logging.rst
new file mode 100644 (file)
index 0000000..65e7692
--- /dev/null
+++ b/docs/logging.rst
@@ -0,0 +1,35 @@
+.. _logging:
+
+*******
+Logging
+*******
+
+Tweepy uses the :mod:`logging` standard library module.
+
+The simplest way to set up logging is using :func:`logging.basicConfig`, e.g.::
+
+    import logging
+    
+    logging.basicConfig(level=logging.DEBUG)
+
+This will output logging from Tweepy, as well as other libraries (like Tweepy's
+dependencies) that use the :mod:`logging` module, directly to the console.
+
+The optional ``level`` argument can be any
+:ref:`logging level <python:levels>`.
+
+To configure logging for Tweepy (or each individual library) specifically, you
+can use :func:`logging.getLogger` to retrieve the logger for the library. For
+example::
+
+    import logging
+    
+    logger = logging.getLogger("Tweepy")
+    logger.setLevel(logging.DEBUG)
+    handler = logging.FileHandler(filename="tweepy.log")
+    logger.addHandler(handler)
+
+More advanced configuration is possible with the :mod:`logging` module.
+For more information, see the
+:doc:`logging module documentation <python:library/logging>` and
+:doc:`tutorials <python:howto/logging>`.