Merge branch 'master' into admin

5 files changed, 105 insertions, 59 deletions

diff --git a/docs/index.rst b/docs/index.rst
index cd32a1f6..a40a5f62 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -17,6 +17,7 @@
 
     mitmproxy
     mitmdump
+    mitmweb
     config
 
 .. toctree::
diff --git a/docs/install.rst b/docs/install.rst
index 1fe09aca..93b3c364 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -3,118 +3,144 @@
 Installation
 ============
 
-.. _install-ubuntu:
+Please follow the steps for your operating system.
 
-Installation On Ubuntu
-----------------------
+Once installation is complete, you can run :ref:`mitmproxy`, :ref:`mitmdump` or
+:ref:`mitmweb` from a terminal.
 
-Ubuntu comes with Python but we need to install pip, python-dev and several libraries.
-This was tested on a fully patched installation of Ubuntu 16.04.
+
+.. _install-macos:
+
+Installation on macOS
+---------------------
+
+You can use Homebrew to install everything:
 
 .. code:: bash
 
-   sudo apt-get install python3-pip python3-dev libffi-dev libssl-dev libtiff5-dev libjpeg8-dev zlib1g-dev libwebp-dev
-   sudo pip3 install mitmproxy  # or pip install --user mitmproxy
+    brew install mitmproxy
 
-On older Ubuntu versions, e.g., **12.04** and **14.04**, you may need to install a newer version of Python.
-mitmproxy requires Python 3.5 or higher. Please take a look at pyenv_.
-Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
+Or you can download the pre-built binary packages from `mitmproxy.org`_.
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
 
+.. _install-windows:
 
-.. _install-fedora:
+Installation on Windows
+-----------------------
 
-Installation On Fedora
-----------------------
+The recommended way to install mitmproxy on Windows is to use the installer
+provided at `mitmproxy.org`_. After installation, you'll find shortcuts for
+:ref:`mitmweb` (the web-based interface) and :ref:`mitmdump` in the start menu.
+Both executables are  added to your PATH and can be invoked from the command
+line.
 
-Fedora comes with Python but we need to install pip, python-dev and several libraries.
-This was tested on a fully patched installation of Fedora 24.
+.. note::
+    mitmproxy's console interface is not supported on Windows, but you can use
+    mitmweb (the web-based interface) and mitmdump.
 
-.. code:: bash
+.. _install-linux:
 
-   sudo dnf install make gcc redhat-rpm-config python3-pip python3-devel libffi-devel openssl-devel libtiff-devel libjpeg-devel zlib-devel libwebp-devel openjpeg2-devel
-   sudo pip3 install mitmproxy  # or pip install --user mitmproxy
+Installation on Linux
+---------------------
 
-Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
+The recommended way to run mitmproxy on Linux is to use the pre-built binaries
+provided at `mitmproxy.org`_.
+
+Our pre-built binaries provide you with the latest version of mitmproxy, a
+self-contained Python 3.5 environment and a recent version of OpenSSL that
+supports HTTP/2. Of course, you can also install mitmproxy from source if you
+prefer that (see :ref:`install-advanced`).
+
+.. _install-advanced:
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
+Advanced Installation
+---------------------
 
+.. _install-docker:
+
+Docker Images
+^^^^^^^^^^^^^
+
+You can also use the official mitmproxy images from `DockerHub`_. That being
+said, our portable binaries are just as easy to install and even easier to use. 😊
 
 
 .. _install-arch:
 
-Installation On Arch Linux
---------------------------
+Installation on Arch Linux
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 mitmproxy has been added into the [community] repository. Use pacman to install it:
 
 >>> sudo pacman -S mitmproxy
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
 
+.. _install-source-ubuntu:
 
-.. _install-macos:
+Installation from Source on Ubuntu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Installation On macOS
-------------------------
+Ubuntu comes with Python but we need to install pip3, python3-dev and several
+libraries. This was tested on a fully patched installation of Ubuntu 16.04.
 
-You can use Homebrew to install everything:
 .. code:: bash
 
-    brew install mitmproxy
+   sudo apt-get install python3-pip python3-dev libffi-dev libssl-dev libtiff5-dev libjpeg8-dev zlib1g-dev libwebp-dev
+   sudo pip3 install mitmproxy  # or pip3 install --user mitmproxy
 
-Or you can download the pre-built binary packages from `mitmproxy.org`_.
+On older Ubuntu versions, e.g., **12.04** and **14.04**, you may need to install
+a newer version of Python. mitmproxy requires Python 3.5 or higher. Please take
+a look at pyenv_. Make sure to have an up-to-date version of pip by running
+``pip3 install -U pip``.
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
 
+.. _install-source-fedora:
 
+Installation from Source on Fedora
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. _install-windows:
+Fedora comes with Python but we need to install pip3, python3-dev and several
+libraries. This was tested on a fully patched installation of Fedora 24.
 
-Installation On Windows
------------------------
-
-.. note::
-    Please note that mitmdump is the only component of mitmproxy that is supported on Windows at
-    the moment.
+.. code:: bash
 
-    **There is no interactive user interface on Windows.**
+   sudo dnf install make gcc redhat-rpm-config python3-pip python3-devel libffi-devel openssl-devel libtiff-devel libjpeg-devel zlib-devel libwebp-devel openjpeg2-devel
+   sudo pip3 install mitmproxy  # or pip3 install --user mitmproxy
 
+Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
 
-First, install the latest version of Python 3.5 from the `Python website`_.
-If you already have an older version of Python 3.5 installed, make sure to install pip_
-(pip is included in Python by default). If pip aborts with an error, make sure you are using the current version of pip.
 
-.. code:: powershell
 
-    python -m pip install --upgrade pip
+.. _install-source-windows:
 
-Next, add Python and the Python Scripts directory to your **PATH** variable.
-You can do this easily by running the following in powershell:
+🐱💻 Installation from Source on Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code:: powershell
+.. note::
+    mitmproxy's console interface is not supported on Windows, but you can use
+    mitmweb (the web-based interface) and mitmdump.
 
-    [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27;C:\Python27\Scripts", "User")
+First, install the latest version of Python 3.5 or later from the `Python
+website`_. During installation, make sure to select `Add Python to PATH`.
 
 Now, you can install mitmproxy by running
 
 .. code:: powershell
 
-    pip install mitmproxy
+    pip3 install mitmproxy
 
-Once the installation is complete, you can run :ref:`mitmdump` from a command prompt.
 
 
-.. _install-source:
+.. _install-dev-version:
 
-Installation From Source
-------------------------
+Latest Development Version
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you would like to install mitmproxy directly from the master branch on GitHub or would like to
-get set up to contribute to the project, install the dependencies as you would for a regular
-mitmproxy installation. Then see the Hacking_ section of the README on GitHub.
-You can check your system information by running: ``mitmproxy --sysinfo``
+If you would like to install mitmproxy directly from the master branch on GitHub
+or would like to get set up to contribute to the project, install the
+dependencies as you would for a regular installation from source. Then see the
+Hacking_ section of the README on GitHub. You can check your system information
+by running: ``mitmproxy --sysinfo``
 
 
 .. _Hacking: https://github.com/mitmproxy/mitmproxy/blob/master/README.rst#hacking
@@ -122,3 +148,4 @@ You can check your system information by running: ``mitmproxy --sysinfo``
 .. _`Python website`: https://www.python.org/downloads/windows/
 .. _pip: https://pip.pypa.io/en/latest/installing.html
 .. _pyenv: https://github.com/yyuu/pyenv
+.. _DockerHub: https://hub.docker.com/r/mitmproxy/mitmproxy/
diff --git a/docs/mitmweb.rst b/docs/mitmweb.rst
new file mode 100644
index 00000000..e57af059
--- /dev/null
+++ b/docs/mitmweb.rst
@@ -0,0 +1,18 @@
+.. _mitmweb:
+.. program:: mitmweb
+
+mitmweb
+=======
+
+**mitmweb** is mitmproxy's web-based user interface that allows interactive
+examination and modification of HTTP traffic. Like mitmproxy, 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.
+
+.. warning::
+
+  Mitmweb is currently in beta. We consider it stable for all features currently
+  exposed in the UI, but it still misses a lot of mitmproxy's features.
+
+
+.. image:: screenshots/mitmweb.png
diff --git a/docs/screenshots/mitmweb.png b/docs/screenshots/mitmweb.png
new file mode 100644
index 00000000..5f0cc925
--- /dev/null
+++ b/docs/screenshots/mitmweb.png
diff --git a/docs/scripting/overview.rst b/docs/scripting/overview.rst
index 84f2135e..6ec0caaa 100644
--- a/docs/scripting/overview.rst
+++ b/docs/scripting/overview.rst
@@ -85,8 +85,8 @@ and mitmproxy console can place script output in the event buffer.
 
 Here's how this looks:
 
-.. literalinclude:: ../../examples/simple/logging.py
-   :caption: :src:`examples/simple/logging.py`
+.. literalinclude:: ../../examples/simple/log_events.py
+   :caption: :src:`examples/simple/log_events.py`
    :language: python
 
 The ``ctx`` module also exposes the mitmproxy master object at ``ctx.master``