docs++

10 files changed, 211 insertions, 9 deletions

diff --git a/docs/clientreplay.rst b/docs/clientreplay.rst
new file mode 100644
index 00000000..9b19befe
--- /dev/null
+++ b/docs/clientreplay.rst
@@ -0,0 +1,4 @@
+.. _clientreplay:
+
+Client-side replay
+==================
\ No newline at end of file
diff --git a/docs/conf.py b/docs/conf.py
index 65aa19dc..1581b055 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -56,7 +56,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'mitmproxy dev docs'
+project = u'mitmproxy docs'
 copyright = u'2015, the mitmproxy project'
 author = u'The mitmproxy project'
 
diff --git a/docs/config.rst b/docs/config.rst
new file mode 100644
index 00000000..ec96d154
--- /dev/null
+++ b/docs/config.rst
@@ -0,0 +1,4 @@
+.. _config:
+
+Configuration
+=============
\ No newline at end of file
diff --git a/docs/dev/models.rst b/docs/dev/models.rst
index ef370f09..850d89f5 100644
--- a/docs/dev/models.rst
+++ b/docs/dev/models.rst
@@ -19,6 +19,7 @@ Models
     :undoc-members:
 
     .. autoclass:: Headers
+        :show-inheritance:
         :members:
         :special-members:
         :no-undoc-members:
\ No newline at end of file
diff --git a/docs/filters.rst b/docs/filters.rst
new file mode 100644
index 00000000..d2363150
--- /dev/null
+++ b/docs/filters.rst
@@ -0,0 +1,4 @@
+.. _filters:
+
+Filters
+=======
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index 7c792ea4..33aa7b41 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,6 +17,13 @@
 
     mitmproxy
     mitmdump
+    config
+
+.. toctree::
+    :hidden:
+    :caption: Features
+
+    filters
 
 .. toctree::
     :hidden:
diff --git a/docs/mitmdump.rst b/docs/mitmdump.rst
index c56903ec..d9b4a26b 100644
--- a/docs/mitmdump.rst
+++ b/docs/mitmdump.rst
@@ -1,4 +1,66 @@
 .. _mitmdump:
+.. program:: mitmdump
 
 mitmdump
-========
\ No newline at end of file
+========
+
+
+**mitmdump** is the command-line companion to mitmproxy. It provides
+tcpdump-like functionality to let you view, record, and programmatically
+transform HTTP traffic. See the :option:`--help` flag output for complete
+documentation.
+
+
+
+Examples
+--------
+
+Saving traffic
+^^^^^^^^^^^^^^
+
+>>> mitmdump -w outfile
+
+Start up mitmdump in proxy mode, and write all traffic to **outfile**. 
+
+
+Filtering saved traffic
+^^^^^^^^^^^^^^^^^^^^^^^
+
+>>> mitmdump -nr infile -w outfile "~m post"
+
+Start mitmdump without binding to the proxy port (:option:`-n`), read all flows from
+infile, apply the specified filter expression (only match POSTs), and write to
+outfile.
+
+
+Client replay
+^^^^^^^^^^^^^
+
+>>> mitmdump -nc outfile
+
+Start mitmdump without binding to the proxy port (:option:`-n`), then replay all
+requests from outfile (:option:`-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
+
+See the :ref:`clientreplay` section for more information.
+
+
+Running a script
+^^^^^^^^^^^^^^^^
+
+>>> mitmdump -s examples/add_header.py
+
+This runs the **add_header.py** example script, which simply adds a new header
+to all responses.
+
+Scripted data transformation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+>>> mitmdump -ns examples/add_header.py -r srcfile -w dstfile
+
+This command loads flows from **srcfile**, transforms it according to the
+specified script, then writes it back to **dstfile**.
+
diff --git a/docs/mitmproxy.rst b/docs/mitmproxy.rst
index b39a8f87..fa3b57c7 100644
--- a/docs/mitmproxy.rst
+++ b/docs/mitmproxy.rst
@@ -1,4 +1,126 @@
 .. _mitmproxy:
+.. program:: mitmproxy
 
 mitmproxy
-=========
\ No newline at end of file
+=========
+
+
+**mitmproxy** is a console tool that allows interactive examination and
+modification of HTTP traffic. It differs from mitmdump in that all flows are
+kept in memory, which means that it's intended for taking and manipulating
+small-ish samples. Use the :kbd:`?` shortcut key to view, context-sensitive
+documentation from any **mitmproxy** screen.
+
+Flow list
+---------
+
+The flow list shows an index of captured flows in chronological order.
+
+.. image:: screenshots/mitmproxy.png
+
+- **1**: A GET request, returning a 302 Redirect response.
+- **2**: A GET request, returning 16.75kb of text/html data.
+- **3**: A replayed request.
+- **4**: Intercepted flows are indicated with orange text. The user may edit
+  these flows, and then accept them (using the :kbd:`a` key) to continue. In this
+  case, the request has been intercepted on the way to the server.
+- **5**: A response intercepted from the server on the way to the client.
+- **6**: The event log can be toggled on and off using the :kbd:`e` shortcut key. This
+  pane shows events and errors that may not result in a flow that shows up in the
+  flow pane.
+- **7**: Flow count.
+- **8**: Various information on mitmproxy's state. In this case, we have an
+  interception pattern set to ``.*``.
+- **9**: Bind address indicator - mitmproxy is listening on port 8080 of all
+  interfaces.
+
+
+Flow view
+---------
+
+The **Flow View** lets you inspect and manipulate a single flow:
+
+.. image:: screenshots/mitmproxy-flowview.png
+
+- **1**: Flow summary.
+- **2**: The Request/Response tabs, showing you which part of the flow you are
+  currently viewing. In the example above, we're viewing the Response. Hit :kbd:`tab`
+  to switch between the Response and the Request.
+- **3**: Headers.
+- **4**: Body.
+- **5**: View Mode indicator. In this case, we're viewing the body in **hex** mode. The other
+  available modes are **pretty**, which uses a number of heuristics to show you a friendly
+  view of various content types, and **raw**, which shows you exactly what's there without any
+  changes. You can change modes using the :kbd:`m` key.
+
+
+Grid Editor
+-----------
+
+Much of the data that we'd like to interact with in mitmproxy is structured.
+For instance, headers, queries and form data can all be thought of as a list of
+key/value pairs. Mitmproxy has a built-in editor that lays this type of data
+out in a grid for easy manipulation.
+
+At the moment, the Grid Editor is used in four parts of mitmproxy:
+
+  - Editing request or response headers (:kbd:`e` for edit, then :kbd:`h` for headers in flow view)
+  - Editing a query string (:kbd:`e` for edit, then :kbd:`q` for query in flow view)
+  - Editing a URL-encoded form (:kbd:`e` for edit, then :kbd:`f` for form in flow view)
+  - Editing replacement patterns (:kbd:`o` for options, then :kbd:`R` for Replacement Patterns)
+
+If there is is no data, an empty editor will be started to let you add some.
+Here is the editor showing the headers from a request:
+
+.. image:: screenshots/mitmproxy-kveditor.png
+
+To edit, navigate to the key or value you want to modify using the arrow or vi
+navigation keys, and press enter. The background color will change to show that
+you are in edit mode for the specified field:
+
+.. image:: screenshots/mitmproxy-kveditor-editmode.png
+
+Modify the field as desired, then press escape to exit edit mode when you're
+done. You can also add a row (:kbd:`a` key), delete a row (:kbd:`d` key), spawn an
+external editor on a field (:kbd:`e` key). Be sure to consult the context-sensitive
+help (:kbd:`?` key) for more.
+
+Example: Interception
+---------------------
+
+**mitmproxy**'s interception functionality lets you pause an HTTP request or
+response, inspect and modify it, and then accept it to send it on to the server
+or client.
+
+
+1: Set an interception pattern
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-filt.png
+
+We press :kbd:`i` to set an interception pattern. In this case, the ``~q`` filter
+pattern tells **mitmproxy** to intercept all requests. For complete filter
+syntax, see the :ref:`filters` section of the documentation,
+or the built-in help function in **mitmproxy**.
+
+2: Intercepted connections are indicated with orange text:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-mid.png
+
+3: You can now view and modify the request:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-options.png
+
+In this case, we viewed the request by selecting it, pressed :kbd:`e` for "edit"
+and :kbd:`m` for "method" to change the HTTP request method.
+
+4: Accept the intercept to continue:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: screenshots/mitmproxy-intercept-result.png
+
+Finally, we press :kbd:`a` to accept the modified request, which is then sent on to
+the server. In this case, we changed the request from an HTTP GET to
+OPTIONS, and Google's server has responded with a 405 "Method not allowed".
diff --git a/docs/modes.rst b/docs/modes.rst
index ccd1f3ee..197c0525 100644
--- a/docs/modes.rst
+++ b/docs/modes.rst
@@ -25,7 +25,7 @@ Mitmproxy's regular mode is the simplest and the easiest to set up.
 1. Start mitmproxy.
 2. Configure your client to use mitmproxy by explicitly setting an HTTP proxy.
 3. Quick Check: You should already be able to visit an unencrypted HTTP site through the proxy.
-4. Open the magic domain <strong>mitm.it</strong> and install the certificate for your device.
+4. Open the magic domain **mitm.it** and install the certificate for your device.
 
 .. note::
     Unfortunately, some applications bypass the system HTTP proxy settings - Android applications
@@ -91,7 +91,7 @@ In this scenario, we would:
 2. Configure the client to use the proxy machine's IP as the default gateway.
 3. Quick Check: At this point, you should already be able to visit an
    unencrypted HTTP site over the proxy.
-4. Open the magic domain <strong>mitm.it</strong> and install the certificate
+4. Open the magic domain **mitm.it**mitm and install the certificate
    for your device.
 
 Setting the custom gateway on clients can be automated by serving the settings
diff --git a/docs/scripting/inlinescripts.rst b/docs/scripting/inlinescripts.rst
index 9b5ced5b..5914def8 100644
--- a/docs/scripting/inlinescripts.rst
+++ b/docs/scripting/inlinescripts.rst
@@ -152,10 +152,8 @@ The main classes you will deal with in writing mitmproxy scripts are:
     - An HTTP response.
 :py:class:`~libmproxy.models.Error`
     - A communications error.
-:py:class:`netlib.odict.ODDict`
-    - A dictionary-like object for managing sets of key/value data. There
-      is also a variant called ODictCaseless that ignores key case for some
-      calls (used mainly for headers).
+:py:class:`netlib.http.Headers`
+    - A dictionary-like object for managing HTTP headers.
 :py:class:`netlib.certutils.SSLCert`
     - Exposes information SSL certificates.
 :py:class:`libmproxy.flow.FlowMaster`