Merge pull request #27 from aavogt/master

documentation update

.ghci

+:set -package ghc
+:set -package ghc-paths
+:set -optP-include -optPdist/build/autogen/cabal_macros.h
+:set -XOverloadedStrings

IHaskell/Completion.hs

 {-# LANGUAGE PatternGuards #-}
-{- | very approximate completion. Seems to generate what is required by
+{- | Description : generates tab-completion options
+
+ very approximate completion. Seems to generate what is required by
  <http://ipython.org/ipython-doc/dev/development/messaging.html#complete>,
  but for whatever reason nothing gets added when the liftIO below prints
  stuff like:

IHaskell/Config.hs

 {-# LANGUAGE QuasiQuotes #-}
+-- | Description : IPython configuration files are compiled-into IHaskell
 module IHaskell.Config (ipython, notebook, console, qtconsole, customjs) where
 
 import Data.String.Here

IHaskell/Eval/Evaluate.hs

 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE NoImplicitPrelude #-}
--- | This module exports all functions used for evaluation of IHaskell input.
+{- | Description : Wrapper around GHC API, exposing a single `evaluate` interface that runs
+                   a statement, declaration, import, or directive.
+
+This module exports all functions used for evaluation of IHaskell input.
+-}
 module IHaskell.Eval.Evaluate (
   interpret, evaluate, Interpreter, liftIO
   ) where

IHaskell/IPython.hs

+-- | Description : Shell scripting wrapper using @Shelly@ for the @notebook@, @setup@, and
+--                 @console@ commands.
 module IHaskell.IPython (
   runIHaskell,
   setupIPythonProfile,

IHaskell/Message/Parser.hs

 {-# LANGUAGE OverloadedStrings #-}
 {-# LANGUAGE NoImplicitPrelude #-}
--- | This module is responsible for converting from low-level ByteStrings
--- | obtained from the 0MQ sockets into Messages. The only exposed function is
--- | `parseMessage`, which should only be used in the low-level 0MQ interface.
+-- | Description : Parsing messages received from IPython
+--
+-- This module is responsible for converting from low-level ByteStrings
+-- obtained from the 0MQ sockets into Messages. The only exposed function is
+-- `parseMessage`, which should only be used in the low-level 0MQ interface.
 module IHaskell.Message.Parser (parseMessage) where
 
 import ClassyPrelude

IHaskell/Message/UUID.hs

--- | Generate, parse, and pretty print UUIDs for use with IPython.
+-- | Description : UUID generator and data structure
+--
+-- Generate, parse, and pretty print UUIDs for use with IPython.
 module IHaskell.Message.UUID (
   UUID,
   random, randoms,

IHaskell/Message/Writer.hs

 {-# LANGUAGE CPP #-}
--- | This module contains the @ToJSON@ instance for @Message@.
+-- | Description : @ToJSON@ for Messages
+--
+-- This module contains the @ToJSON@ instance for @Message@.
 module IHaskell.Message.Writer (
   ToJSON(..)
 )  where

IHaskell/Types.hs

 {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
+-- | Description : All message type definitions.
 module IHaskell.Types (
   Profile (..),
   Message (..),

IHaskell/ZeroMQ.hs

--- | The "ZeroMQ" module abstracts away the low-level 0MQ based interface with IPython,
+-- | Description : Low-level ZeroMQ communication wrapper.
+--
+-- The "ZeroMQ" module abstracts away the low-level 0MQ based interface with IPython,
 -- replacing it instead with a Haskell Channel based interface. The `serveProfile` function
 -- takes a IPython profile specification and returns the channel interface to use.
 module IHaskell.ZeroMQ (

Main.hs

 {-# LANGUAGE NoImplicitPrelude #-}
 {-# LANGUAGE OverloadedStrings #-}
+-- | Description : Argument parsing and basic messaging loop, using Haskell
+--                 Chans to communicate with the ZeroMQ sockets. 
+module Main where
 import ClassyPrelude hiding (liftIO)
 import Control.Concurrent.Chan
 import Data.Aeson
@@ -39,7 +42,8 @@ main = do
     ["kernel", profileSrc] -> kernel profileSrc
 
     -- Bad arguments.
-    [] -> putStrLn "Provide command to run ('setup', 'kernel <profile-file.json>', 'run <app> [args]')."
+    [] -> putStrLn "Provide command to run ('setup', 'kernel <profile-file.json>', \
+                                           \'notebook [args]', 'console [args]')."
     cmd:_ -> putStrLn $ "Unknown command: " ++ pack cmd
 
 

README.md

@@ -100,18 +100,8 @@ cabal build
 ```
 
 Loading IHaskell into GHCi for testing:
-If you want to play around with IHaskell by loading it into GHCi, you need to include the ghc package and the cabal macros file. cabal_macros.h is generated by the ```cabal build``` command and the file is placed in the build directory. You will also need to use the OverloadedStrings language extension. So if you are at the top level of the IHaskell project, you can load GHCi as follows: 
-```bash
-ghci -XOverloadedStrings -package ghc -optP-include -optPdist/build/autogen/cabal_macros.h
-```
-
-or you can create a .ghci file in the top level directory, like so: 
-
-```bash
-# In the IHaskell .ghci file
-:set -package ghc
-:set -package ghc-paths
-:set -optP-include -optPdist/build/autogen/cabal_macros.h
-:set -XOverloadedStrings
-```
-
+If you are at the top level of the IHaskell project, you can load GHCi with
+`cabal repl` or `ghci`. The first option hides all packages not listed in the
+`IHaskell.cabal`, while the second option only sets a couple options given in
+the `.ghci` file in the repo.  Once in ghci, it can then be useful to `:load
+*IHaskell/Config` or similar.