Adding 'interactive' module and documentation which provides an envir…

…onment for use within interactive sessions.

docs/index.rst

@@ -18,6 +18,7 @@ User Documentation
    :maxdepth: 1
 
    installation
+   interactive
    samples
    acquisition
 

docs/interactive.rst

@@ -0,0 +1,37 @@
+
+================================================
+Interactive usage (:mod:`peregrine.interactive`)
+================================================
+
+In addition to being a stand-alone tool, Peregrine is designed with interactive use in mind. Working from an interactive session such as `IPython <http://ipython.org/>`_ provides a great environment for exploring GNSS data sets and rapidly prototyping new algorithms.
+
+We particularly recommend using the `IPython notebook frontend <http://ipython.org/ipython-doc/dev/interactive/htmlnotebook.html>`_ with pylab::
+
+  ipython notebook --pylab inline
+
+Peregrine functions and classes are arranged within a heirarchy of modules and
+submodules grouping similar functionality together. This provides a logical
+structure when writing scripts but when working interactively it is more
+convenient to have all the commonly used functions available from within the
+same namespace, such that they can all be imported together.
+
+The :mod:`peregrine.interactive` module provides this unified namespace and
+also configures the python :mod:`logging` module (which is used for reporting
+throughout the library) for output into the interactive session.
+
+.. note::
+  Throughout this documentation there are many examples which take the form of
+  an interactive session. In these examples we will always use the explicit
+  full module path for clarity. Of course, you can save yourself some typing by
+  using the :mod:`peregrine.interactive` namespace instead.
+
+.. note::
+  The :mod:`peregrine.interactive` namespace is intended as a convenience for
+  use in interactive sessions, if you are writing a script it is recommended
+  that you use full module paths.
+
+peregrine.interactive Module
+----------------------------
+
+.. automodule:: peregrine.interactive
+

peregrine/interactive.py

@@ -0,0 +1,75 @@
+# Copyright (C) 2012 Swift Navigation Inc.
+#
+# This source is subject to the license found in the file 'LICENSE' which must
+# be be distributed together with this source. All other rights reserved.
+#
+# THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
+# EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
+
+"""
+The :mod:`peregrine.interactive` module sets up a default logging configuration
+and imports the most commonly used Peregrine functions and classes into one
+namespace. This is designed to provide a convenient environment for use in
+interactive sessions such as from within `IPython <http://ipython.org/>`_.
+
+It is designed to be star imported as follows::
+
+  from peregrine.interactive import *
+
+:mod:`peregrine.interactive` Functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:mod:`peregrine.interactive` defines the following functions:
+
+.. currentmodule:: peregrine.interactive
+
+.. autosummary:: configure_logging
+
+Included Functions
+^^^^^^^^^^^^^^^^^^
+
+The following classes, functions and attributes from other modules are
+available in the interactive namespace:
+
+"""
+
+def configure_logging():
+  """ Configure python :mod:`logging` for use in an interactive session."""
+  import logging
+  logging.basicConfig(
+    level=logging.DEBUG,
+    format="\033[2K\r%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+  )
+configure_logging()
+
+from peregrine.acquisition import *
+from peregrine.samples import *
+from peregrine.include.generateCAcode import caCodes
+from peregrine.analysis.acquisition import *
+from peregrine.analysis.samples import *
+
+# Some may find this to be in very bad taste but we are going to alter our own
+# docstring to automatically provide a summary of the functions and classes
+# available in the interactive namespace.
+
+# First find all the local variables (including functions, classes etc.) that
+# have a module starting with 'peregrine', i.e. they are part of our library.
+l = dict(locals())
+peregrine_items = {}
+for k, v in l.iteritems():
+  if hasattr(v, '__module__'):
+    if v.__module__.startswith('peregrine'):
+      if not v.__module__ in peregrine_items:
+        peregrine_items[v.__module__] = []
+      peregrine_items[v.__module__] += [k]
+# Remove items defined here in interactive, we will document them explicitly in
+# the docstring.
+del peregrine_items['peregrine.interactive']
+# Now add autosummaries to our docstring grouping items from the same module
+# together.
+for mod in sorted(peregrine_items.iterkeys()):
+  __doc__ += ".. currentmodule:: %s\n\n" % mod
+  __doc__ += ".. rubric:: Included from :mod:`%s`:\n\n" % mod
+  for name in sorted(peregrine_items[mod]):
+    __doc__ += ".. autosummary:: %s\n\n" % name