edit docs

.gitignore

@@ -1,16 +1,17 @@
+__pycache__/
 .*.swp
 .DS_Store
+.ipynb_checkpoints
+.jarjar
+.venv*/
 *.pyc
 *.sublime-project
-test.py
-update-pip.sh
-dist/
 build/
-jarjar.egg-info/
-venv*/
-.venv*/
+build/
+dist/
 install.log
 jarjar-shell
-build/
-.ipynb_checkpoints
-.jarjar
+jarjar.egg-info/
+test.py
+update-pip.sh
+venv*/

README.md

@@ -35,9 +35,14 @@ For the bleeding edge:
 pip install git+https://github.com/AusterweilLab/jarjar.git
 ```
 
-My guess is that you'll want to create jarjar's config file, `~/.jarjar`. This tells jarjar what you'd like to use as a default for your slack team's webhook, the channel to post to, and the message it sends. Don't worry, you can over-ride these anytime.
+My guess is that you'll want to create jarjar's config file, `.jarjar`. This
+tells jarjar what you'd like to use as a default for your slack team's webhook,
+the channel to post to, and the message it sends. Don't worry, you can over-ride
+these anytime.
 
-Edit this snippet and add it to `~/.jarjar`:
+Jarjar automatically looks for `.jarjar` in the current working directory as
+well as the user home (`~`), so edit this snippet and throw it one of those
+places:
 
 ```shell
 channel='@username'
@@ -54,19 +59,15 @@ Use the jarjar python api like:
 ```python
 from jarjar import jarjar
 
-# initialize a jarjar object
 jj = jarjar() # defaults from .jarjar
-jj = jarjar(channel='#channel', webhook='slack-webhook-url')
-jj = jarjar(webhook='slack-webhook-url')
-
-# send a text message
 jj.text('Hi!')
-jj.text('Hi!', channel=["@jeffzemla", "#channel"])
 
 # send an attachment
 jj.attach({'meesa': 'jarjar binks'}, message='Hello!')
 ```
 
+Jarjar also supports [decorator and Jupyter magic workflows](docs/python-workflows.md)!
+
 ### Command Line Tool
 
 We also made a [command line tool](docs/clt.md) for use outside of python scripts. The command line tool adds functionality to execute processes and send messages when they are complete.
@@ -92,4 +93,6 @@ We're on [Read The Docs](http://jarjar.readthedocs.io/en/latest/)!
 
 ## Having Trouble? Or a feature request?
 
-We are terrible developers and you'll probably run into all sorts of problems. Don't be shy, [file an issue on github](https://github.com/AusterweilLab/jarjar/issues/new)!
+We are terrible developers and you'll probably run into all sorts of problems.
+Don't be shy,
+[file an issue on github](https://github.com/AusterweilLab/jarjar/issues/new)!

docs/index.rst

@@ -44,11 +44,14 @@ Install
 
    pip install jarjar
 
-My guess is that you'll want to create jarjar's config file, ``~/.jarjar``. This tells jarjar
-what you'd like to use as a default for your slack team's webhook, the channel to post to,
-and the message it sends. Don't worry, you can over-ride these anytime.
+My guess is that you'll want to create jarjar's config file, ``.jarjar``.
+This tells jarjar what you'd like to use as a default for your slack team's
+webhook, the channel to post to, and the message it sends. Don't worry, you can
+over-ride these anytime.
 
-Edit this snippet and add it to ``~/.jarjar``:
+Jarjar automatically looks for ``.jarjar`` in the current working directory as
+well as the user home (``~``), so edit this snippet and throw it one of those
+places:
 
 .. code-block:: shell
 
@@ -68,18 +71,16 @@ Use the :doc:`jarjar python api </api>` like:
 
     from jarjar import jarjar
 
-    # initialize a jarjar object
     jj = jarjar() # defaults from .jarjar
-    jj = jarjar(channel='#channel', webhook='slack-webhook-url')
-    jj = jarjar(webhook='slack-webhook-url')
-
-    # send a text message
     jj.text('Hi!')
-    jj.text('Hi!', channel=["@jeffzemla", "#channel"])
 
     # send an attachment
     jj.attach({'meesa': 'jarjar binks'}, message='Hello!')
 
+
+
+Jajrar also supports :doc:`decorator and Jupyter magic workflows </python-workflows>`!
+
 Command Line Tool
 -----------------
 
@@ -112,3 +113,4 @@ Detailed Documention
    install
    clt
    api
+   python-workflows

docs/python-workflows.md

@@ -0,0 +1,84 @@
+# Python API Workflows
+
+Jarjar is great for letting you know when come snippet of code has finished
+executing, but configuring things properly can be a little bit of a hassle.
+
+A common workflow involves writing your code and then throwing a jarjar call
+at the end:
+
+```python
+from jarjar import jarjar
+jj = jarjar()
+
+def fun(long_list):
+  results = []
+  for i in long_list:
+    if i == 'something':
+      results.append('something')
+    else:
+      results.append('something else')
+  return results
+
+# run the process, notify on completion
+results = fun(a_long_list)
+jj.text('Process complete!')
+```
+
+That looks good, but what if an exception was raised on the way? So maybe you
+edit like so:
+
+```python
+try:
+  results = fun(my_long_list)
+  jj.text('Process complete!')
+except Exception:
+  jj.text('Process Failed?')
+```
+
+That's great. But what if you want to run many such processes? Or what if you
+want to run the same process twice, getting a notification each time? What if
+you wanted to include the traceback within the message if there was an
+exception?
+
+You'll end up writing a lot more code just to handle jarjar notifications.
+Luckily, we wrote that code for you.
+
+## Jarjar decorator
+
+You can decorate a function and jarjar will handle exceptions for you. You'll
+get a notification whenever the function exits, and it will include the
+traceback if there was an exception:
+
+```python
+@jj.decorate
+def fun(long_list):
+  # ...
+
+results = fun(my_long_list)
+```
+
+## Jupyter cell magic
+
+Jupyter notebooks are becoming a standard in scientific work. Packaged with
+jarjar is a Jupyter magic so that users can be notified about a cell's
+execution.
+
+You first need to register the magic, and then you can use it freely. In one
+cell:
+
+```python
+from jarjar import jarjar
+jj = jarjar()
+
+jj.register_magic()
+```
+
+Then in a later cell:
+
+```python
+%%jarjar
+results = fun(my_long_list)
+```
+
+You'll get a notification whether your cell executed successfully or not, and it
+will include the traceback if there was an exception.

tests/adhoc.py

@@ -4,9 +4,9 @@
 jj = jarjar()
 
 @jj.decorate
-def f(a=1):
+def fun(a=1):
     time.sleep(a)
-    kfkdfsk
+    int('a')
 
 
-f(3)
+fun(3)