docs: improve external source links, tweak code docs

docs/conf.py

@@ -195,20 +195,19 @@ html_show_sourcelink = False
 htmlhelp_basename = 'mitmproxydoc'
 
 
+SRCBASE = "https://github.com/mitmproxy/mitmproxy/blob/master"
+
+
 # FIXME: change master to dynamic version before release
 extlinks = dict(
-    src = ('https://github.com/mitmproxy/mitmproxy/blob/master/%s', '')
+    src = (SRCBASE + r"/%s", '')
 )
 
 
-MODULE = "/mitmproxy/"
-
 def linkcode_resolve(domain, info):
     if domain != 'py':
         return None
     module, fullname = info['module'], info['fullname']
-    # TODO: attributes/properties don't have modules, maybe try to look
-    #       them up based on their cached host object?
     if not module:
         return None
     obj = importlib.import_module(module)
@@ -217,19 +216,19 @@ def linkcode_resolve(domain, info):
     if obj is None:
         return None
     try:
-        obj = getattr(obj, '_orig')
-    except AttributeError:
-        pass
-    try:
-        obj_source_path = inspect.getsourcefile(obj)
+        spath = inspect.getsourcefile(obj)
         _, line = inspect.getsourcelines(obj)
     except (TypeError, IOError):
-        # obj doesn't have a module, or something
         return None
-    off = obj_source_path.rfind(MODULE)
-    mpath = obj_source_path[off + len(MODULE):]
-    print(obj_source_path, mpath)
-    return "https://github.com/mitmproxy/mitmproxy/blob/master/%s" % mpath
+    if spath.rfind("netlib") > -1:
+        off = spath.rfind("netlib")
+        mpath = spath[off:]
+    elif spath.rfind("mitmproxy") > -1:
+        off = spath.rfind("mitmproxy")
+        mpath = spath[off:]
+    else:
+        return None
+    return SRCBASE + "/%s#L%s" % (mpath, line)
 
 
 def setup(app):

docs/scripting/api.rst

@@ -1,8 +1,22 @@
 .. _api:
 
-API
-====
 
-.. automodule:: mitmproxy.models.http
+API
+===
+
+- HTTP
+    - `mitmproxy.models.http.HTTPRequest <#mitmproxy.models.http.HTTPRequest>`_
+    - `mitmproxy.models.http.HTTPResponse <#mitmproxy.models.http.HTTPResponse>`_
+    - `mitmproxy.models.http.HTTPFlow <#mitmproxy.models.http.HTTPFlow>`_
+
+HTTP
+----
+
+.. autoclass:: mitmproxy.models.http.HTTPRequest
+    :inherited-members:
+
+.. autoclass:: mitmproxy.models.http.HTTPResponse
+    :inherited-members:
+
+.. autoclass:: mitmproxy.models.http.HTTPFlow
     :inherited-members:
-    :members: HTTPFlow, HTTPRequest, HTTPResponse

mitmproxy/models/http.py

@@ -12,10 +12,11 @@ class HTTPRequest(http.Request):
 
     """
     A mitmproxy HTTP request.
-    This is a very thin wrapper on top of :py:class:`netlib.http.Request` and
-    may be removed in the future.
     """
 
+    # This is a very thin wrapper on top of :py:class:`netlib.http.Request` and
+    # may be removed in the future.
+
     def __init__(
             self,
             first_line_format,
@@ -98,9 +99,9 @@ class HTTPResponse(http.Response):
 
     """
     A mitmproxy HTTP response.
-    This is a very thin wrapper on top of :py:class:`netlib.http.Response` and
-    may be removed in the future.
     """
+    # This is a very thin wrapper on top of :py:class:`netlib.http.Response` and
+    # may be removed in the future.
 
     def __init__(
             self,
@@ -148,29 +149,30 @@ class HTTPResponse(http.Response):
 class HTTPFlow(flow.Flow):
 
     """
-    A HTTPFlow is a collection of objects representing a single HTTP
+    An HTTPFlow is a collection of objects representing a single HTTP
     transaction.
-
-    Attributes:
-        request: :py:class:`HTTPRequest` object
-        response: :py:class:`HTTPResponse` object
-        error: :py:class:`Error` object
-        server_conn: :py:class:`ServerConnection` object
-        client_conn: :py:class:`ClientConnection` object
-        intercepted: Is this flow currently being intercepted?
-        live: Does this flow have a live client connection?
-
-    Note that it's possible for a Flow to have both a response and an error
-    object. This might happen, for instance, when a response was received
-    from the server, but there was an error sending it back to the client.
     """
 
     def __init__(self, client_conn, server_conn, live=None):
         super(HTTPFlow, self).__init__("http", client_conn, server_conn, live)
+
         self.request = None
-        """@type: HTTPRequest"""
+        """ :py:class:`HTTPRequest` object """
         self.response = None
-        """@type: HTTPResponse"""
+        """ :py:class:`HTTPResponse` object """
+        self.error = None
+        """ :py:class:`Error` object
+
+        Note that it's possible for a Flow to have both a response and an error
+        object. This might happen, for instance, when a response was received
+        from the server, but there was an error sending it back to the client.
+        """
+        self.server_conn = server_conn
+        """ :py:class:`ServerConnection` object """
+        self.client_conn = client_conn
+        """:py:class:`ClientConnection` object """
+        self.intercepted = False
+        """ Is this flow currently being intercepted? """
 
     _stateobject_attributes = flow.Flow._stateobject_attributes.copy()
     _stateobject_attributes.update(