added logging doc

--HG--
extra : convert_revision : svn%3Ab85faa78-f9eb-468e-a121-7cced6da292c%40704

scrapy/trunk/docs/ref/index.rst

@@ -14,4 +14,5 @@ This section documents the API of Scrapy |version|. For more information see :re
    extensions
    settings
    signals
+   logging
    email

scrapy/trunk/docs/ref/logging.rst

@@ -0,0 +1,85 @@
+.. _ref-logging:
+
+=======
+Logging
+=======
+
+Scrapy logging facility is provided by the ``scrapy.log`` module, and is
+currently implemented as a wrapper for `Twisted logging`_.
+
+.. _Twisted logging: http://twistedmatrix.com/projects/core/documentation/howto/logging.html
+
+Logging must be started through the ``scrapy.log.start`` function.
+
+Quick example
+=============
+
+Here's a quick example of how to log a message using the ``WARNING`` level::
+
+    from scrapy.log
+    log.msg("This is a warning", level=log.WARNING)
+
+scrapy.log module
+=================
+
+.. module:: scrapy.log
+   :synopsis: Logging facility
+
+.. attribute:: log_level
+
+   The current log level being used
+
+.. attribute:: started
+
+   A boolean which is ``True`` is logging has been started or ``False`` otherwise.
+
+.. function:: start(logfile=None, loglevel=None, log_stdout=None)
+
+    Start the logging facility. This must be called before actually logging any
+    messages. Otherwise, messages logged before this call will get lost.
+
+    ``logfile`` is a string with the file path to use for logging output. If
+    omitted, :setting:`LOGFILE` setting will be used. If both are ``None``, log
+    will be sent to standard output (if ``log_stdout`` or :setting:`LOG_STDOUT` is
+    ``True``) or standard error (if ``log_stderr`` or :setting:`LOG_STDOUT` is
+    ``False``).
+
+    ``loglevel`` is the logging level. Availables ones are:
+        * ``scrapy.log.CRITICAL``
+        * ``scrapy.log.ERROR``
+        * ``scrapy.log.WARNING``
+        * ``scrapy.log.INFO``
+        * ``scrapy.log.DEBUG``
+
+    ``log_stdout`` is a boolean which specifies if log should be sent to standard
+    output (if ``True``) or standard error (if ``False``)
+
+.. function:: msg(message, level=INFO, component=BOT_NAME, domain=None)
+
+    Log a message
+
+    ``message`` is a string with the message to log
+
+    ``level`` is the log level for this message. See ``start()`` function for
+    available log levels.
+
+    ``component`` is a string with the component to use for logging, it defaults to :setting:`BOT_NAME`
+
+    ``domain`` is a string with the domain to use for logging this message.
+    This parameter should always be used when logging stuff paricular to any
+    domain or spider.
+
+.. function:: exc(message, level=ERROR, component=BOT_NAME, domain=None)
+
+    Log an exception. Similar to ``msg()`` but it also appends a stack trace
+    report using `traceback.format_exc`.
+
+    .. _traceback.format_exc: http://docs.python.org/library/traceback.html#traceback.format_exc
+
+    ``message`` - same as ``msg()`` function
+    
+    ``level`` - same as ``msg()`` function
+
+    ``component`` - same as ``msg()`` function
+
+    ``domain`` - same as ``msg()`` function