fix my refs and segment out the Logger API docs a bit. need a better …

…intro for them.

docs/faq.rst

@@ -62,7 +62,7 @@ Background questions
 Unlike the design questions above, background questions relate to just
 the objective facts.
 
-.. ref:: etymology
+.. _etymology:
 
 What's with the name, Lithoxyl, what's that even mean?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/logger.rst

@@ -1,7 +1,48 @@
 The Logger
-==============
+==========
 
 .. automodule:: lithoxyl.logger
 
 .. autoclass:: lithoxyl.logger.Logger
-   :members:
+
+Record creation
+~~~~~~~~~~~~~~~
+
+The Logger is primarily used through its
+:class:`~lithoxyl.record.Record`-creating convenience methods named
+after various log levels: :meth:`~Logger.debug`, :meth:`~Logger.info`,
+and :meth:`~Logger.critical`.
+
+Each creates a new :term:`record` with a given name, passing any
+additional keyword arguments on through to the
+:class:`lithoxyl.record.Record` constructor.
+
+.. automethod:: lithoxyl.logger.Logger.debug
+.. automethod:: lithoxyl.logger.Logger.info
+.. automethod:: lithoxyl.logger.Logger.critical
+
+The record level can also be passed in:
+
+.. automethod:: lithoxyl.logger.Logger.record
+
+Sink registration
+~~~~~~~~~~~~~~~~~
+
+Another vital aspect of Loggers is the :ref:`registration and
+management of Sinks <configuring_sinks>`.
+
+.. autoattribute:: lithoxyl.logger.Logger.sinks
+.. automethod:: lithoxyl.logger.Logger.add_sink
+.. automethod:: lithoxyl.logger.Logger.set_sinks
+.. automethod:: lithoxyl.logger.Logger.clear_sinks
+
+Event handling
+~~~~~~~~~~~~~~
+
+The event handling portion of the Logger API exists for Logger-Sink
+interactions.
+
+.. automethod:: lithoxyl.logger.Logger.on_begin
+.. automethod:: lithoxyl.logger.Logger.on_end
+.. automethod:: lithoxyl.logger.Logger.on_warn
+.. automethod:: lithoxyl.logger.Logger.on_exception

docs/overview.rst

@@ -14,28 +14,30 @@ logging. Traditions that included leaving it all as an afterthought,
 only added once things break.
 
 Logging is not the last step anymore. Lithoxyl makes instrumentation
-worthwhile from day 1, so developers design for introspectability
-from the start. Lithoxyl takes full advantage of Python's rich syntax
-and runtime to provide valuable features, from metrics collection to
-structured logging to interactive debugging hooks.
+worthwhile from day 1, so projects are designed for introspectability
+from the ground up. Lithoxyl takes full advantage of Python's rich
+syntax and runtime to provide valuable features, from metrics
+collection to structured logging to interactive debugging hooks.
 
-The Lithoxyl approach to application instrumentation is a practical
-one. First, write some code. Then, once you have half a module or find
-yourself asking, "How long does this part take?" then it's time to
-``pip install lithoxyl``. After that, here are two steps. First comes
-instrumentation, then we get into configuration.
+The Lithoxyl approach to application instrumentation is
+practical. First, write some code. Then, once you have half a module
+or find yourself asking, "How long does this part take?" then it's
+time to ``pip install lithoxyl``.
+
+Integrating Lithoxyl comes down to two steps, instrumentation and
+configuration. First, instrumentation.
 
 Instrumenting with Records
 --------------------------
 
 With Lithoxyl, all instrumentation, including logging, starts with
 knowing your application. We want to find the important parts of your
-application. Then, we wrap them in microtransactions, called Records.
+application and wrap them in microtransactions, called Records.
 
-Records are much more than print statements. Records are objects. Each
-Record has a name and level, for aggregation and filtering. More
-importantly, Records track the state of code execution, from timing
-information to uncaught exceptions.
+Records are much more than print statements. Records are lightweight
+objects that track the state of code execution, from timing
+information to uncaught exceptions. Plus, each Record has a name and
+a level, to enable aggregation and filtering down the line.
 
 Records are created with Loggers. Here's a basic example of creating
 an *info*-level Record with a preconfigured Logger:
@@ -149,6 +151,8 @@ your application, no matter how many aspects it may have. On their
 own, they are conceptually useful, but without Sinks, they are all
 potential.
 
+.. _configuring_sinks:
+
 Configuring Sinks
 -----------------
 

lithoxyl/logger.py

@@ -72,18 +72,9 @@ class Logger(object):
         module (str): Name of the module where the new Logger instance
             will be stored.  Defaults to the module of the caller.
 
-    The Logger is primarily used through its
-    :class:`~lithoxyl.record.Record`-creating methods named after
-    various log levels:
-
-        * :meth:`Logger.critical`
-        * :meth:`Logger.info`
-        * :meth:`Logger.debug`
-
-    Each creates a new :term:`record` with a given name, passing any
-    additional keyword arguments on through to the
-    :class:`lithoxyl.record.Record` constructor.
-
+    Most Logger methods and attributes fal into three categories:
+    :class:`~lithoxyl.record.Record` creation, Sink registration, and
+    Event handling.
     """
 
     record_type = Record