From 09beb1aa13685584f2f77dfdf1935ae6056e7aea Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Tue, 2 Feb 2021 23:34:26 +0100 Subject: [PATCH] docs: add api reference using pdoc --- docs/scripts/api.py | 66 +++++++++++++++++++ docs/scripts/pdoc-template/frame.html.jinja2 | 2 + docs/scripts/pdoc-template/module.html.jinja2 | 3 + docs/src/content/api/_index.md | 10 +++ docs/src/content/api/mitmproxy.flow.md | 11 ++++ docs/src/content/api/mitmproxy.http.md | 11 ++++ .../content/api/mitmproxy.proxy.context.md | 11 ++++ docs/src/content/api/mitmproxy.tcp.md | 11 ++++ docs/src/content/api/mitmproxy.websocket.md | 11 ++++ docs/src/layouts/partials/edit-on-github.html | 3 +- docs/src/layouts/partials/sidemenu.html | 16 ++++- mitmproxy/flow.py | 6 ++ mitmproxy/proxy/context.py | 8 +++ setup.py | 1 + 14 files changed, 165 insertions(+), 5 deletions(-) create mode 100755 docs/scripts/api.py create mode 100644 docs/scripts/pdoc-template/frame.html.jinja2 create mode 100644 docs/scripts/pdoc-template/module.html.jinja2 create mode 100644 docs/src/content/api/_index.md create mode 100644 docs/src/content/api/mitmproxy.flow.md create mode 100644 docs/src/content/api/mitmproxy.http.md create mode 100644 docs/src/content/api/mitmproxy.proxy.context.md create mode 100644 docs/src/content/api/mitmproxy.tcp.md create mode 100644 docs/src/content/api/mitmproxy.websocket.md diff --git a/docs/scripts/api.py b/docs/scripts/api.py new file mode 100755 index 000000000..e2af27450 --- /dev/null +++ b/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 +""") diff --git a/docs/scripts/pdoc-template/frame.html.jinja2 b/docs/scripts/pdoc-template/frame.html.jinja2 new file mode 100644 index 000000000..576dd761b --- /dev/null +++ b/docs/scripts/pdoc-template/frame.html.jinja2 @@ -0,0 +1,2 @@ +{% block style %}{% endblock %} +{% block body %}{% endblock %} diff --git a/docs/scripts/pdoc-template/module.html.jinja2 b/docs/scripts/pdoc-template/module.html.jinja2 new file mode 100644 index 000000000..728a9b4dc --- /dev/null +++ b/docs/scripts/pdoc-template/module.html.jinja2 @@ -0,0 +1,3 @@ +{% extends "default/module.html.jinja2" %} +{% block nav %}{% endblock %} +{% block style_layout %}{% endblock %} diff --git a/docs/src/content/api/_index.md b/docs/src/content/api/_index.md new file mode 100644 index 000000000..911e96639 --- /dev/null +++ b/docs/src/content/api/_index.md @@ -0,0 +1,10 @@ + +--- +title: "API Reference" +layout: single +menu: + addons: + weight: 5 +--- + +# API Reference diff --git a/docs/src/content/api/mitmproxy.flow.md b/docs/src/content/api/mitmproxy.flow.md new file mode 100644 index 000000000..0837998c1 --- /dev/null +++ b/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" >}} diff --git a/docs/src/content/api/mitmproxy.http.md b/docs/src/content/api/mitmproxy.http.md new file mode 100644 index 000000000..69496d5c2 --- /dev/null +++ b/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" >}} diff --git a/docs/src/content/api/mitmproxy.proxy.context.md b/docs/src/content/api/mitmproxy.proxy.context.md new file mode 100644 index 000000000..e11c6c494 --- /dev/null +++ b/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" >}} diff --git a/docs/src/content/api/mitmproxy.tcp.md b/docs/src/content/api/mitmproxy.tcp.md new file mode 100644 index 000000000..59553d49d --- /dev/null +++ b/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" >}} diff --git a/docs/src/content/api/mitmproxy.websocket.md b/docs/src/content/api/mitmproxy.websocket.md new file mode 100644 index 000000000..0f70619d5 --- /dev/null +++ b/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" >}} diff --git a/docs/src/layouts/partials/edit-on-github.html b/docs/src/layouts/partials/edit-on-github.html index d2c3098c2..a5de09108 100644 --- a/docs/src/layouts/partials/edit-on-github.html +++ b/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")) }} {{ end }} - diff --git a/docs/src/layouts/partials/sidemenu.html b/docs/src/layouts/partials/sidemenu.html index 035cc59e8..919abf3cf 100644 --- a/docs/src/layouts/partials/sidemenu.html +++ b/docs/src/layouts/partials/sidemenu.html @@ -3,9 +3,19 @@ {{ $currentPage := .ctx }} {{ $menuname := .menuname }} {{ range $menu.ByWeight }} -
  • +
  • {{ .Name }} + href="{{.URL}}">{{ .Name }} + {{ if and .HasChildren (or ($currentPage.IsMenuCurrent $menuname .) ($currentPage.HasMenuCurrent $menuname .)) }} + + {{ end }}
    • {{end}} - \ No newline at end of file + diff --git a/mitmproxy/flow.py b/mitmproxy/flow.py index bf2278950..5c9b81291 100644 --- a/mitmproxy/flow.py +++ b/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", +] diff --git a/mitmproxy/proxy/context.py b/mitmproxy/proxy/context.py index 6a21504d9..396c8b9df 100644 --- a/mitmproxy/proxy/context.py +++ b/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", +] diff --git a/setup.py b/setup.py index 9d83017e0..cecf29760 100644 --- a/setup.py +++ b/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",