First draft of scripting docs.

5 files changed, 106 insertions, 52 deletions

diff --git a/doc-src/02-docstyle.css b/doc-src/02-docstyle.css
index eee82c58..b3d55e1a 100644
--- a/doc-src/02-docstyle.css
+++ b/doc-src/02-docstyle.css
@@ -52,14 +52,21 @@ a {
     color: #181818;
 }
 
+
+#bd h3 {
+    margin-bottom: 0px;
+
+}
+
 #bd p {
     margin: 1em 0;
+    margin-top: 0.5em;
 }
 
 /* Keyboard shortcuts */
 #bd em {
     font-weight: bold;
-    color: #04B404; 
+    color: #00A700; 
     font-style: normal;
 }
 
@@ -86,10 +93,9 @@ pre {
 }
 
 .terminal {
-    color: #ffffff;
+    color: #c0c0c0;
+    font-size: 1em;
     background: #000000;
-
-
 }
 
 .docindex {
@@ -118,5 +124,22 @@ li a {
 .highlight {
     font-size: 14px;
 }
+.example_legend{
+    float: right;
+    line-height: 1;
+    margin-left: 20px;
+    font-size: 12px;
+}
+.example pre {
+    margin: 0;
+
+}
+
 
 
+
+.kvtable th {
+    text-align: left;
+    white-space: nowrap;
+}
+
diff --git a/doc-src/index.py b/doc-src/index.py
index 34704f7e..6241a232 100644
--- a/doc-src/index.py
+++ b/doc-src/index.py
@@ -34,7 +34,8 @@ ns.index_contents = file(mpath("README.mkd")).read()
 top = os.path.abspath(os.getcwd())
 def example(s):
     d = file(mpath(s)).read()
-    return countershape.template.Syntax("py")(d)
+    extemp = """<div class="example">%s<div class="example_legend">(%s)</div></div>"""
+    return extemp%(countershape.template.Syntax("py")(d), s)
 
 
 ns.example = example
diff --git a/doc-src/mitmdump.html b/doc-src/mitmdump.html
index 4d0683ea..1ca5a020 100644
--- a/doc-src/mitmdump.html
+++ b/doc-src/mitmdump.html
@@ -8,28 +8,36 @@ documentation.
 
 ## Example: saving traffic
 
-    mitmdump -w outfile
+<pre class="terminal">
+mitmdump -w outfile
+</pre>
 
 Start up mitmdump in proxy mode, and write all traffic to __outfile__. 
 
 
 ## Example: client replay
 
-    mitmdump -nc outfile
+<pre class="terminal">
+mitmdump -nc outfile
+</pre>
 
 Start mitmdump without binding to the proxy port (_-n_), then replay all
 requests from outfile (_-c filename_). Flags combine in the obvious way, so
 you can replay requests from one file, and write the resulting flows to
 another:
 
-    mitmdump -nc srcfile -w dstfile
+<pre class="terminal">
+mitmdump -nc srcfile -w dstfile
+</pre>
 
 See the [Client-side Replay](@!urlTo("clientreplay.html")!@) section for more information.
 
 
 ## Example: running a script
 
-    mitmdump -s examples/add_header.py
+<pre class="terminal">
+mitmdump -s examples/add_header.py
+</pre>
 
 This runs the __add_header.py__ example script, which simply adds a new header
 to all responses.
@@ -37,7 +45,9 @@ to all responses.
 
 ## Example: scripted data transformation
 
-    mitmdump -ns examples/add_header.py -r srcfile -w dstfile
+<pre class="terminal">
+mitmdump -ns examples/add_header.py -r srcfile -w dstfile
+</pre>
 
 This command loads flows from __srcfile__, transforms it according to the
 specified script, then writes it back to __dstfile__.
diff --git a/doc-src/scripts.html b/doc-src/scripts.html
index 990ca070..af140901 100644
--- a/doc-src/scripts.html
+++ b/doc-src/scripts.html
@@ -1,47 +1,71 @@
 
-__mitmproxy__ has a powerful event-drive scripting API, that allows you to
-modify flows on-the-fly or rewrite previously saved flows locally. 
+__mitmproxy__ has a powerful scripting API that allows you to modify flows
+on-the-fly or rewrite previously saved flows locally. 
+
+The mitmproxy scripting API is event driven - a script is simply a Python
+module that exposes a set of event methods. Here's a complete mitmproxy script
+that adds a new header to every HTTP response before it is returned to the
+client:
+
+$!example("examples/add_header.py")!$
+
+The first argument to each event method is an instance of ScriptContext that
+lets the script interact with the global mitmproxy state. The __response__
+event also gets an instance of Flow, which we can use to manipulate the
+response itself.
 
 
 ## Events
 
-<table>
-    <tr>
-        <td>start(ctx)</td>
-        <td>Called once on startup, before any other events.</td>
-    </tr>
-    <tr>
-        <td>clientconnect(ctx, ClientConnect)</td>
-        <td>Called when a client initiates a connection to the proxy. Note that
-        a connection can correspond to multiple HTTP requests.</td>
-    </tr>
-    <tr>
-        <td>request(ctx, Flow)</td>
-        <td>Called when a client request has been received.</td>
-    </tr>
-    <tr>
-        <td>response(ctx, Flow)</td>
-        <td>Called when a server response has been received.</td>
-    </tr>
-    <tr>
-        <td>error(ctx, Flow)</td>
-        <td>Called when a flow error has occured, e.g. invalid server
-        responses, or interrupted connections. This is distinct from a valid
-        server HTTP error response, which is simply a response with an HTTP
-        error code. </td>
-    </tr>
-    <tr>
-        <td>clientdisconnect(ctx, ClientDisconnect)</td>
-        <td>Called when a client disconnects from the proxy.</td>
-    </tr>
-    <tr>
-        <td>done(ctx)</td>
-        <td>Called once on script shutdown, after any other events.</td>
-    </tr>
-</table>
+### start(ScriptContext)
+
+Called once on startup, before any other events.
+
+
+###clientconnect(ScriptContext, ClientConnect)
+
+Called when a client initiates a connection to the proxy. Note that
+a connection can correspond to multiple HTTP requests.
+
+
+###request(ScriptContext, Flow)
+
+Called when a client request has been received. The __Flow__ object is
+guaranteed to have a non-None __request__ attribute.
+
+
+### response(ScriptContext, Flow)
+
+Called when a server response has been received. The __Flow__ object is
+guaranteed to have non-None __request__ and __response__ attributes.
+
+
+### error(ScriptContext, Flow)
+
+Called when a flow error has occured, e.g. invalid server responses, or
+interrupted connections. This is distinct from a valid server HTTP error
+response, which is simply a response with an HTTP error code. The __Flow__
+object is guaranteed to have non-None __request__ and __error__ attributes.
+
+
+### clientdisconnect(ScriptContext, ClientDisconnect)
+
+Called when a client disconnects from the proxy.
 
+### done(ScriptContext)
 
+Called once on script shutdown, after any other events.
 
 
+## Scripts on saved flows
 
+There are a few circumstances in which a script may run on Flows that are
+already complete. For example, you could start a script, and then load a saved
+set of flows from a file (see the scripted data transformation example on the
+[mitmdump](@!urlTo("mitmdump.html")!@) page). This also happens when you run a
+one-shot script on a single flow through the _|_ (pipe) shortcut in mitmproxy.
 
+In this case, there are no client connections, and the events are run in the
+following order: __start__, __request__, __response__, __error__, __done__.  If
+the flow doesn't have a __response__ or __error__ associated with it, the
+matching event will be skipped.
diff --git a/examples/add_header.py b/examples/add_header.py
index 6ddeab3d..0c0593d1 100644
--- a/examples/add_header.py
+++ b/examples/add_header.py
@@ -1,6 +1,2 @@
-"""
-    This script adds a new header to all responses.
-"""
-
-def response(ctx, f):
-    f.response.headers["newheader"] = ["foo"]
+def response(context, flow):
+    flow.response.headers["newheader"] = ["foo"]