docs: cleanups improvements and fighting sphinx

- Hide links to internal code listings, and link to github instead
- Improve formatting of code/example captions
- Fix outdated documentation of command-line options
- Complete documentation of all events + improved formatting
- tcp_open -> tcp_start, tcp_close -> tcp_end to reduce confusion

1 files changed, 202 insertions, 0 deletions

diff --git a/docs/scripting/events.rst b/docs/scripting/events.rst
new file mode 100644
index 00000000..c16c01f6
--- /dev/null
+++ b/docs/scripting/events.rst
@@ -0,0 +1,202 @@
+.. _events:
+
+Events
+=======
+
+General
+-------
+
+.. list-table::
+    :widths: 40 60
+    :header-rows: 0
+
+    *   - .. py:function:: configure(options, updated)
+        - Called once on startup, and whenever options change.
+
+          *options*
+            An ``options.Options`` object with the total current configuration
+            state of mitmproxy.
+          *updated*
+            A set of strings indicating which configuration options have been
+            updated. This contains all options when *configure* is called on
+            startup, and only changed options subsequently.
+
+    *   - .. py:function:: done()
+        - Called once when the script shuts down, either because it's been
+          unloaded, or because the proxy itself is shutting down.
+
+    *   - .. py:function:: log(entry)
+        - Called whenever an event log is added.
+
+          *entry*
+            An ``controller.LogEntry`` object - ``entry.msg`` is the log text,
+            and ``entry.level`` is the urgency level ("debug", "info", "warn",
+            "error").
+
+    *   - .. py:function:: start()
+        - Called once on startup, before any other events. If you return a
+          value  from this event, it will replace the current addon. This
+          allows you to, "boot into" an addon implemented as a class instance
+          from the module level.
+
+    *   - .. py:function:: tick()
+        - Called at a regular sub-second interval as long as the addon is
+          executing.
+
+
+Connection
+----------
+
+.. list-table::
+    :widths: 40 60
+    :header-rows: 0
+
+    *   - .. py:function:: clientconnect(root_layer)
+        - Called when a client initiates a connection to the proxy. Note that a
+          connection can correspond to multiple HTTP requests.
+
+          *root_layer*
+            The root layer (see `mitmproxy.protocol` for an explanation what
+            the root layer is), provides transparent access to all attributes
+            of the :py:class:`~mitmproxy.proxy.RootContext`. For example,
+            ``root_layer.client_conn.address`` gives the remote address of the
+            connecting client.
+
+    *   - .. py:function:: clientdisconnect(root_layer)
+        - Called when a client disconnects from the proxy.
+
+          *root_layer*
+            The root layer object.
+
+    *   - .. py:function:: next_layer(layer)
+
+        - Called whenever layers are switched. You may change which layer will
+          be used by returning a new layer object from this event.
+
+          *layer*
+            The next layer, as determined by mitmpmroxy.
+
+    *   - .. py:function:: serverconnect(server_conn)
+        - Called before the proxy initiates a connection to the target server.
+          Note that a connection can correspond to multiple HTTP requests.
+
+          *server_conn*
+            A ``ServerConnection`` object. It is guaranteed to have a non-None
+            ``address`` attribute.
+
+    *   - .. py:function:: serverdisconnect(server_conn)
+        - Called when the proxy has closed the server connection.
+
+          *server_conn*
+            A ``ServerConnection`` object.
+
+
+HTTP Events
+-----------
+
+.. list-table::
+    :widths: 40 60
+    :header-rows: 0
+
+    *   - .. py:function:: request(flow)
+        - Called when a client request has been received.
+
+          *flow*
+            A ``models.HTTPFlow`` object. At this point, the flow is
+            guaranteed to have a non-None ``request`` attribute.
+
+    *   - .. py:function:: requestheaders(flow)
+        - Called when the headers of a client request have been received, but
+          before the request body is read.
+
+          *flow*
+            A ``models.HTTPFlow`` object. At this point, the flow is
+            guaranteed to have a non-None ``request`` attribute.
+
+    *   - .. py:function:: responseheaders(flow)
+
+        - Called when the headers of a server response have been received, but
+          before the response body is read.
+
+          *flow*
+            A ``models.HTTPFlow`` object. At this point, the flow is
+            guaranteed to have a non-none ``request`` and ``response``
+            attributes, however the response will have no content.
+
+    *   - .. py:function:: response(flow)
+
+        - Called when a server response has been received.
+
+          *flow*
+            A ``models.HTTPFlow`` object. At this point, the flow is
+            guaranteed to have a non-none ``request`` and ``response``
+            attributes. The raw response body will be in ``response.body``,
+            unless response streaming has been enabled.
+
+    *   - .. py:function:: error(flow)
+        - Called when a flow error has occurred, 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.
+
+          *flow*
+            The flow containing the error. It is guaranteed to have
+            non-None ``error`` attribute.
+
+
+WebSocket Events
+-----------------
+
+.. list-table::
+    :widths: 40 60
+    :header-rows: 0
+
+    *   - .. py:function:: websockets_handshake(flow)
+
+        - Called when a client wants to establish a WebSockets connection. The
+          WebSockets-specific headers can be manipulated to manipulate the
+          handshake. The ``flow`` object is guaranteed to have a non-None
+          ``request`` attribute.
+
+          *flow*
+            The flow containing the HTTP websocket handshake request. The
+            object is guaranteed to have a non-None ``request`` attribute.
+
+
+TCP Events
+----------
+
+These events are called only if the connection is in :ref:`TCP mode
+<tcpproxy>`. So, for instance, TCP events are not called for ordinary HTTP/S
+connections.
+
+.. list-table::
+    :widths: 40 60
+    :header-rows: 0
+
+    *   - .. py:function:: tcp_end(flow)
+        - Called when TCP streaming ends.
+
+          *flow*
+            A ``models.TCPFlow`` object.
+
+    *   - .. py:function:: tcp_error(flow)
+        - Called when a TCP error occurs - e.g. the connection closing
+          unexpectedly.
+
+          *flow*
+            A ``models.TCPFlow`` object.
+
+    *   - .. py:function:: tcp_message(flow)
+
+        - Called a TCP payload is received from the client or server. The
+          sender and receiver are identifiable. The most recent message will be
+          ``flow.messages[-1]``. The message is user-modifiable.
+
+          *flow*
+            A ``models.TCPFlow`` object.
+
+    *   - .. py:function:: tcp_start(flow)
+        - Called when TCP streaming starts.
+
+          *flow*
+            A ``models.TCPFlow`` object.