docs: add api reference using pdoc

docs/scripts/api.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+import os
+import shutil
+from pathlib import Path
+
+import pdoc.render
+
+here = Path(__file__).parent
+
+if os.environ.get("DOCS_ARCHIVE", False):
+    edit_url_map = {}
+else:
+    edit_url_map = {
+        "mitmproxy": "https://github.com/mitmproxy/mitmproxy/blob/master/mitmproxy/",
+    }
+
+pdoc.render.configure(
+    template_directory=here / "pdoc-template",
+    edit_url_map=edit_url_map,
+)
+
+modules = [
+    "mitmproxy.proxy.context",
+    "mitmproxy.http",
+    "mitmproxy.flow",
+    "mitmproxy.tcp",
+    "mitmproxy.websocket",
+]
+
+pdoc.pdoc(
+    *modules,
+    output_directory=here / ".." / "src" / "generated" / "api"
+)
+
+api_content = here / ".." / "src" / "content" / "api"
+if api_content.exists():
+    shutil.rmtree(api_content)
+
+api_content.mkdir()
+
+for module in modules:
+    filename = f"api/{ module.replace('.','/') }.html"
+    (api_content / f"{module}.md").write_text(f"""
+---
+title: "{module}"
+url: "{filename}"
+
+menu:
+    addons:
+        parent: 'API Reference'
+---
+
+{{{{< readfile file="/generated/{filename}" >}}}}
+""")
+
+(api_content / f"_index.md").write_text(f"""
+---
+title: "API Reference"
+layout: single
+menu:
+    addons:
+        weight: 5
+---
+
+# API Reference
+""")

docs/scripts/pdoc-template/frame.html.jinja2

@@ -0,0 +1,2 @@
+{% block style %}{% endblock %}
+{% block body %}{% endblock %}

docs/scripts/pdoc-template/module.html.jinja2

@@ -0,0 +1,3 @@
+{% extends "default/module.html.jinja2" %}
+{% block nav %}{% endblock %}
+{% block style_layout %}{% endblock %}

docs/src/content/api/_index.md

@@ -0,0 +1,10 @@
+
+---
+title: "API Reference"
+layout: single
+menu:
+    addons:
+        weight: 5
+---
+
+# API Reference

docs/src/content/api/mitmproxy.flow.md

@@ -0,0 +1,11 @@
+
+---
+title: "mitmproxy.flow"
+url: "api/mitmproxy/flow.html"
+
+menu:
+    addons:
+        parent: 'API Reference'
+---
+
+{{< readfile file="/generated/api/mitmproxy/flow.html" >}}

docs/src/content/api/mitmproxy.http.md

@@ -0,0 +1,11 @@
+
+---
+title: "mitmproxy.http"
+url: "api/mitmproxy/http.html"
+
+menu:
+    addons:
+        parent: 'API Reference'
+---
+
+{{< readfile file="/generated/api/mitmproxy/http.html" >}}

docs/src/content/api/mitmproxy.proxy.context.md

@@ -0,0 +1,11 @@
+
+---
+title: "mitmproxy.proxy.context"
+url: "api/mitmproxy/proxy/context.html"
+
+menu:
+    addons:
+        parent: 'API Reference'
+---
+
+{{< readfile file="/generated/api/mitmproxy/proxy/context.html" >}}

docs/src/content/api/mitmproxy.tcp.md

@@ -0,0 +1,11 @@
+
+---
+title: "mitmproxy.tcp"
+url: "api/mitmproxy/tcp.html"
+
+menu:
+    addons:
+        parent: 'API Reference'
+---
+
+{{< readfile file="/generated/api/mitmproxy/tcp.html" >}}

docs/src/content/api/mitmproxy.websocket.md

@@ -0,0 +1,11 @@
+
+---
+title: "mitmproxy.websocket"
+url: "api/mitmproxy/websocket.html"
+
+menu:
+    addons:
+        parent: 'API Reference'
+---
+
+{{< readfile file="/generated/api/mitmproxy/websocket.html" >}}

docs/src/layouts/partials/edit-on-github.html

@@ -1,4 +1,4 @@
-{{ if and .IsPage (not (getenv "DOCS_ARCHIVE")) }}
+{{ if and .IsPage (ne .Type "api") (not (getenv "DOCS_ARCHIVE")) }}
 <a class="button is-small is-outlined is-link is-pulled-right"
    target="_blank"
    href="https://github.com/mitmproxy/mitmproxy/blob/master/docs/src/content/{{ .File.Path }}"
@@ -6,4 +6,3 @@
     Edit on GitHub
 </a>
 {{ end }}
-

docs/src/layouts/partials/sidemenu.html

@@ -3,9 +3,19 @@
     {{ $currentPage := .ctx }}
     {{ $menuname := .menuname }}
     {{ range $menu.ByWeight }}
-        <li >
+        <li>
             <a class="{{ if $currentPage.IsMenuCurrent $menuname . }}is-active{{ end }}"
                href="{{.URL}}">{{ .Name }}</a>
+            {{ if and .HasChildren (or ($currentPage.IsMenuCurrent $menuname .) ($currentPage.HasMenuCurrent $menuname .)) }}
+            <ul>
+                {{ range .Children }}
+                    <li>
+                        <a class="{{ if $currentPage.IsMenuCurrent $menuname . }}is-active{{ end }}"
+                           href="{{ .URL }}">{{ .Name }}</a>
+                    </li>
+                {{ end }}
+            </ul>
+            {{ end }}
         </li>
     {{end}}
 </ul>

mitmproxy/flow.py

@@ -185,3 +185,9 @@ class Flow(stateobject.StateObject):
     def timestamp_start(self) -> float:
         """Start time of the flow."""
         return self.client_conn.timestamp_start
+
+
+__all__ = [
+    "Flow",
+    "Error",
+]

mitmproxy/proxy/context.py

@@ -32,3 +32,11 @@ class Context:
         ret.server = self.server
         ret.layers = self.layers.copy()
         return ret
+
+
+__all__ = [
+    "Connection",
+    "Client",
+    "Server",
+    "ConnectionState",
+]

setup.py

@@ -99,6 +99,7 @@ setup(
         'dev': [
             "hypothesis>=5.8,<6.1",
             "parver>=0.1,<2.0",
+            "pdoc>=4.0.0",
             "pytest-asyncio>=0.10.0,<0.14,!=0.14",
             "pytest-cov>=2.7.1,<3",
             "pytest-timeout>=1.3.3,<2",