From 05590cf6c272571aa812ace321aa30573f2e125c Mon Sep 17 00:00:00 2001 From: Aldo Cortesi Date: Thu, 23 Oct 2014 09:44:47 +1300 Subject: [PATCH] Documentation re-org - No longer using README.md in the rendered documentation. - Rendered doc instrutions are now for the released version of mitmproxy, with dev install instructions in the README.md --- README.mkd | 13 +++++++++---- doc-src/index.html | 25 ++++++++++++++++++++++++- doc-src/index.py | 13 ++++++++----- doc-src/install.html | 24 ------------------------ 4 files changed, 41 insertions(+), 34 deletions(-) diff --git a/README.mkd b/README.mkd index 495826128..d0d1f09b9 100644 --- a/README.mkd +++ b/README.mkd @@ -30,8 +30,10 @@ Features Installation ------------ +The recommended way to install mitmproxy is running + +`pip install mitmproxy` -The recommended way to install mitmproxy is running pip install mitmproxy. For convenience, we provide binary packages on [mitmproxy.org](http://mitmproxy.org/). @@ -49,7 +51,8 @@ Optional packages for extended content decoding: * [cssutils](http://cthedot.de/cssutils/) version 1.0 or newer. For convenience, all optional dependencies can be installed with -`pip install mitmproxy[contenviews]` + +`pip install mitmproxy contentviews` __mitmproxy__ is tested and developed on OSX, Linux and OpenBSD. On Windows, only mitmdump is supported, which does not have a graphical user interface. @@ -60,15 +63,17 @@ Hacking The following components are needed if you plan to hack on mitmproxy: -* The test suite requires the `dev` extra requirements listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py) and [pathod](http://pathod.net), version matching mitmproxy. +* The test suite requires the `dev` extra requirements listed in [setup.py](https://github.com/mitmproxy/mitmproxy/blob/master/setup.py) and [pathod](http://pathod.net), version matching mitmproxy. Install these with `pip install mitmproxy dev`. * Rendering the documentation requires [countershape](http://github.com/cortesi/countershape). -For convenience, the following procedure is recommended to set up your environment: +The following procedure is recommended to set up your dev environment: + ``` $ git clone https://github.com/mitmproxy/mitmproxy.git $ cd mitmproxy $ pip install --src . -r requirements.txt ``` + This installs the latest GitHub versions of mitmproxy, netlib and pathod into `mitmproxy/`. All other development dependencies save countershape are installed into their usual locations. Please ensure that all patches are accompanied by matching changes in the test diff --git a/doc-src/index.html b/doc-src/index.html index 79687ec61..23da7223c 100644 --- a/doc-src/index.html +++ b/doc-src/index.html @@ -1,4 +1,27 @@ -@!index_contents!@ +__mitmproxy__ is an interactive, SSL-capable man-in-the-middle proxy for HTTP +with a console interface. + +__mitmdump__ is the command-line version of mitmproxy. Think tcpdump for HTTP. + +__libmproxy__ is the library that mitmproxy and mitmdump are built on. + +Documentation, tutorials and distribution packages can be found on the +mitmproxy.org website: + +[mitmproxy.org](http://mitmproxy.org). +Features +-------- + +- Intercept HTTP requests and responses and modify them on the fly. +- Save complete HTTP conversations for later replay and analysis. +- Replay the client-side of an HTTP conversations. +- Replay HTTP responses of a previously recorded server. +- Reverse proxy mode to forward traffic to a specified server. +- Transparent proxy mode on OSX and Linux. +- Make scripted changes to HTTP traffic using Python. +- SSL certificates for interception are generated on the fly. +- And much, much more. + diff --git a/doc-src/index.py b/doc-src/index.py index b7ab99952..e6064e3a4 100644 --- a/doc-src/index.py +++ b/doc-src/index.py @@ -1,6 +1,8 @@ -import os, sys, datetime +import os +import sys +import datetime import countershape -from countershape import Page, Directory, PythonModule, markup, model +from countershape import Page, Directory, markup, model import countershape.template sys.path.insert(0, "..") from libmproxy import filt, version @@ -23,18 +25,18 @@ ns.docMaintainer = "Aldo Cortesi" ns.docMaintainerEmail = "aldo@corte.si" ns.copyright = u"\u00a9 mitmproxy project, %s" % datetime.date.today().year + def mpath(p): p = os.path.join(MITMPROXY_SRC, p) return os.path.expanduser(p) -with open(mpath("README.mkd")) as f: - readme = f.read() - ns.index_contents = readme.split("\n", 1)[1] #remove first line (contains build status) def example(s): d = file(mpath(s)).read().rstrip() extemp = """
%s
(%s)
""" return extemp%(countershape.template.Syntax("py")(d), s) + + ns.example = example @@ -73,6 +75,7 @@ def nav(page, current, state): ns.nav = nav ns.navbar = countershape.template.File(None, "_nav.html") + pages = [ Page("index.html", "Introduction"), Page("install.html", "Installation"), diff --git a/doc-src/install.html b/doc-src/install.html index 5d4124597..5f1e54fd1 100644 --- a/doc-src/install.html +++ b/doc-src/install.html @@ -4,30 +4,11 @@ release or from source - is to use [pip](http://www.pip-installer.org/). If you don't already have pip on your system, you can find installation instructions [here](http://www.pip-installer.org/en/latest/installing.html). - -## Installing the latest release - -A single command will download and install the latest release of mitmproxy, -along with all its dependencies: - 
 pip install mitmproxy
-## Installing from source - -When installing from source, the easiest method is still to use pip. In this -case run: - -
-pip install /path/to/source
-
- -Note that if you're installing current git master, you will also have to -install the current git master of [netlib](http://github.com/mitmproxy/netlib) by -hand. - ## OSX - If you're running a Python interpreter installed with homebrew (or similar), @@ -64,8 +45,3 @@ from source: - libxslt1-dev - - - - -