bring readme in line

Readme.md

@@ -1,21 +1,43 @@
-Python Build Pack
-====================
-The Python Build Pack (PBP) is a build pack for running Python and Django
-apps on Heroku.
+Heroku buildpack: Python
+========================
 
-If `requirements.txt` is present, the PBP considers the directory a Python app
-with packages to install via pip.
+This is a [Heroku buildpack](http://devcenter.heroku.com/articles/buildpack) for Python apps.
+It uses [virtualenv](http://www.virtualenv.org/) and [pip](http://www.pip-installer.org/).
 
-Furthermore, if `${PROJECT}/settings.py` is present, the PBP considers the
-directory a Python/Django app, and patches `settings.py` to parse the Heroku
-DATABASE_URL config vars. It then sets default process types to use the Django
-web server.
+Usage
+-----
 
-External Build Pack
-----------------------
-Cutting-edge development is taking place in this repo. To use this on Heroku,
-set a `BUILDPACK_URL` config var with a fully authenticated URL to this repo:
+Example usage:
 
-    $ heroku config:add BUILDPACK_URL=https://nzoschke:XXXXXXX@github.com/heroku/heroku-buildpack-python.git
+    $ ls
+    Procfile  requirements.txt  web.py
 
-On next push, slug-compiler will use this BP instead of the built-in one.
+    $ heroku create --stack cedar --buildpack git@github.com:heroku/heroku-buildpack-python.git
+
+    $ git push heroku master
+    ...
+    -----> Heroku receiving push
+    -----> Fetching custom build pack... done
+    -----> Python app detected
+    -----> Preparing virtualenv version 1.6.4
+           New python executable in ./bin/python
+           Installing setuptools............done.
+           Installing pip...............done.
+    -----> Installing dependencies using pip version 1.0.2
+           Downloading/unpacking Flask==0.7.2 (from -r requirements.txt (line 1))
+           Downloading/unpacking Werkzeug>=0.6.1 (from Flask==0.7.2->-r requirements.txt (line 1))
+           Downloading/unpacking Jinja2>=2.4 (from Flask==0.7.2->-r requirements.txt (line 1))
+           Installing collected packages: Flask, Werkzeug, Jinja2
+           Successfully installed Flask Werkzeug Jinja2
+           Cleaning up...
+
+The buildpack will detect your app as Python if it has the file `requirements.txt` in the root. It will detect your app as Python/Django if there is an additional `settings.py` in a project subdirectory.
+
+It will use virtualenv and pip to install your dependencies, vendoring a copy of the Python runtime into your slug.  The `bin/`, `include/` and `lib/` directories will be cached between builds to allow for faster pip install time.
+
+Hacking
+-------
+
+To use this buildpack, fork it on Github.  Push up changes to your fork, then create a test app with `--buildpack <your-github-url>` and push to it.
+
+To change the vendored virtualenv, unpack the desired version to the `src/` folder, and update the virtualenv() function in `bin/compile` to prepend the virtualenv module directory to the path.