From 8382dfea5e0987484d1aa111bb9beb35ec916360 Mon Sep 17 00:00:00 2001 From: "Paul J. Davis" Date: Thu, 6 May 2010 20:55:38 -0400 Subject: [PATCH] Updating webpage docs. --- doc/htdocs/configuration.html | 4 +- doc/htdocs/css/style.css | 11 +- doc/htdocs/deployment.html | 60 +++++------ doc/htdocs/faq.html | 37 ++++--- doc/htdocs/index.html | 13 +-- doc/htdocs/installation.html | 30 +++--- doc/htdocs/news.html | 25 +++-- doc/htdocs/tuning.html | 31 ++++-- doc/htdocs/usage.html | 170 ++++++++++++++++++------------ doc/site/configuration.rst | 4 +- doc/site/deployment.rst | 58 +++++------ doc/site/faq.rst | 42 ++++---- doc/site/index.rst | 19 ++-- doc/site/installation.rst | 42 ++++---- doc/site/news.rst | 31 +++--- doc/site/tuning.rst | 31 ++++-- doc/site/usage.rst | 190 +++++++++++++++++++--------------- 17 files changed, 454 insertions(+), 344 deletions(-) diff --git a/doc/htdocs/configuration.html b/doc/htdocs/configuration.html index 90ca62097..dbacd2ea2 100644 --- a/doc/htdocs/configuration.html +++ b/doc/htdocs/configuration.html @@ -49,7 +49,9 @@

gunicorn

The Configuration File

-

Gunicorn 0.5 introduced the ability to use a Python configuration file. Gunicorn will look for gunicorn.conf.py in the current working directory or what ever path is specified on the command line with the -c option.

+

Gunicorn 0.5 introduced the ability to use a Python configuration file. Gunicorn +will look for gunicorn.conf.py in the current working directory or what ever +path is specified on the command line with the -c option.

Example gunicorn.conf.py

diff --git a/doc/htdocs/css/style.css b/doc/htdocs/css/style.css
index c6948613d..003a6c04a 100644
--- a/doc/htdocs/css/style.css
+++ b/doc/htdocs/css/style.css
@@ -23,10 +23,15 @@ ul {
     padding-left: 1em;
 }
 
+dt {
+    border-top: 1px solid #BBB;
+    padding-top: 0.5em;
+}
+
 dd {
-    border-bottom: 1px solid #eee;
-    margin: 0 0 .5em;
-    padding: 0 0 .5em;
+    margin: 0px;
+    margin-bottom: 0.5em;
+    padding: 0px;
 }
 
 pre {
diff --git a/doc/htdocs/deployment.html b/doc/htdocs/deployment.html
index 6bfa1949c..250f83ee7 100644
--- a/doc/htdocs/deployment.html
+++ b/doc/htdocs/deployment.html
@@ -49,35 +49,33 @@ 
gunicorn

 
   

 
Production Setup

-
There are two general classes of configuration for Gunicorn. For the time
-being these will are referred to as "fast clients" and "sleepy applications".

-

-
Fast Clients

-
Generally speaking when we say "fast clients" what we really mean is that the
-time taken to process a client from the time a socket is accepted until
-the time the socket is closed is well defined to be short. This means that
-clients are buffered by an upstream proxy (otherwise clients can send or
-receive data slowly) and that your application code does not have major
-blocking sections (a web request to the internet might occasionally take a
-non trivial amount of time).

-
Traditional webapps are generally fine for fast client configurations.
-Deployments should generally default to this type of configuration unless it is
-known that the application code wants to do long-polling, comet, web sockets or
-has other potentially long operations (on the order of seconds).

+

+
Synchronous vs Asynchronous workers

+
The default configuration of Gunicorn assumes that your application code is
+mostly CPU bound. The default worker class is a simple single threaded loop that
+just processes requests as they are received. In general, most applications will
+do just fine with this sort of configuration.

+
This CPU bound assumption is why the default configuration needs to use a
+buffering HTTP proxy like Nginx to protect the Gunicorn server. If we allowed
+direct connections a client could send a request slowly thus starving the server
+of free worker processes (because they're all stuck waiting for data).

+
Example use-cases for asynchronous workers:

+

+
    
+
  • Applications making long blocking calls (Ie, to external web services)
    • 
+
  • Serving requests directly to the internet
    • 
+
  • Streaming requests and responses
    • 
+
  • Long polling
    • 
+
  • Web sockets
    • 
+
  • Comet
    • 
+

+

 

-

-
Sleepy Applications

-
Any application that requires an undefined amount of time for client processing
-is considered a sleepy application. If you are wanting a platform that is
-capable of handling comet connections, long polling, or potentially long
-blocking operations (requests to external web services, ie Facebook Connect)
-then you'll want to use an async arbiter.

-

-

-
Nginx Config for fast clients handling

+

+
Basic Nginx Configuration

 
Although there are many HTTP proxies available, we strongly advise that you
 use Nginx. If you choose another proxy server you need to make sure that it
-buffers slow clients when you use default Gunicorn arbiter. Without this
+buffers slow clients when you use default Gunicorn workers. Without this
 buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
 You can use slowloris to check if your proxy is behaving properly.

 
An example configuration file for fast clients with Nginx:

@@ -133,8 +131,12 @@ 
Nginx Config for fast clients handling

     }
 }
-

To handle sleepy applications, just add the line proxy_buffering off; under -the proxy_redirect directive:

+

If you want to be able to handle streaming request/responses or other fancy +features like Comet, Long polling, or Web sockets, you need to turn off the +proxy buffering. When you do this you must run with one of the async worker +classes.

+

To turn off buffering, you only need to add proxy_buffering off; to your +location block:

 ...
 location / {
@@ -148,7 +150,7 @@ 
Nginx Config for fast clients handling

         break;
     }
 }
-....
+...
diff --git a/doc/htdocs/faq.html b/doc/htdocs/faq.html index 8dfaf026f..bc38c22ec 100644 --- a/doc/htdocs/faq.html +++ b/doc/htdocs/faq.html @@ -50,19 +50,19 @@

gunicorn

FAQ

-
What is a fast client?
-
Generally speaking a fast client is something that is being served over the -local network or from the same machine. This generally would refer to requests -forwarded from an upstream proxy. Also see the above FAQ for what a fast -client is not.
-
What is a slow client?
-
A slow client is defined as a request that can take an arbitrary amount of -time to send a request or read a response. Sometimes due to network -performance or because it is a malicious client attempting to cause problems. -Check out the slowloris script to generate slow client traffic.
-
What are sleepy applications?
-
Applications that expect long request/response times and/or slow clients. -Gunicorn use Eventlet or Gevent to manage concurrency.
+
How do I know which type of worker to use?
+
Test. Read the "Synchronous vs Asynchronous workers" section on the +deployment page. Test some more.
+
What types of workers are there?
+

These can all be used with the -k option and specifying them +as egg:gunicorn#$(NAME) where $(NAME) is chosen from this list.

+
    +
  • sync - The default synchronous worker
    • +
  • eventlet - Asynchronous workers based on Greenlets
    • +
  • gevent - Asynchronous workers based on Greenlets
    • +
  • tornado - Asynchronous workers based on FriendFeed's Tornado server.
    • +
+
How might I test a proxy configuration?
Check out slowloris for a script that will generate significant slow traffic. If your application remains responsive through out that test you @@ -83,13 +83,16 @@

FAQ

$ kill -TTOU $masterpid
+
How can I figure out the best number of worker processes?
+
Start gunicorn with an approximate number of worker processes. Then use the +TTIN and/or TTOU signals to adjust the number of workers under load.
How do I set SCRIPT_NAME?
By default SCRIPT_NAME is an empy string. The value could be set by setting SCRIPT_NAME in the environment or as an HTTP header.
-
How to name processes?
-
You need to install the Python package setproctitle. Then you can name -your process with -n or just let the default. If you use a configuration -file you can set the process name with the proc_name option.
+
How can I name processes?
+
You need to install the Python package setproctitle. Then you can specify +a base process name on the command line (-n) or in the configuration +file.
diff --git a/doc/htdocs/index.html b/doc/htdocs/index.html index a2727b5aa..cc0cf9a2e 100644 --- a/doc/htdocs/index.html +++ b/doc/htdocs/index.html @@ -47,15 +47,16 @@

gunicorn

Green Unicorn

-

Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve -fast clients or sleepy applications.

-

This is a port of Unicorn in Python. Meet us on the #gunicorn IRC channel -on Freenode.

+

Gunicorn 'Green Unicorn' is a WSGI HTTP Server for UNIX. It's a pre-fork +worker model ported from Ruby's Unicorn project. The Gunicorn server is +broadly compatible with various web frameworks, simply implemented, light +on server resource usage, and fairly speedy.

+

Feel free to join us in #gunicorn on freenode.

Gunicorn is released under the MIT License. See the LICENSE for more details.

Features

diff --git a/doc/htdocs/installation.html b/doc/htdocs/installation.html index 5de0269e7..bad19e6fd 100644 --- a/doc/htdocs/installation.html +++ b/doc/htdocs/installation.html @@ -52,7 +52,7 @@

Installation

Requirements

    -
  • Python 2.5 or newer (Python 3.x will be supported soon)
    • +
  • Python 2.x >= 2.5 (Python 3.x will be supported soon)
  • setuptools >= 0.6c6
  • nosetests (for the test suite only)
@@ -72,7 +72,7 @@

Installing with easy_install

Installing from source

-

You can install Gunicorn from source as simply as you would install any other +

You can install Gunicorn from source just as you would install any other Python package. Gunicorn uses setuptools which will automatically fetch all dependencies (including setuptools itself).

@@ -97,30 +97,28 @@

Installation

-
-

Installation requirements for sleepy application handling

-

If you want to handle sleepy application you will need to install -Eventlet or Gevent.

+
+

Enabling async workers

+

You may also want to install Eventlet or Gevent if you expect that your +application code may need to pause for extended periods of time during +request processing. Check out the FAQ for more information on when you'll +want to consider one of the alternate worker types.

To install eventlet:

 $ easy_install -U eventlet
-

Replace eventlet with gevent if you want to use the gevent -arbiter.

-

You can now launch gunicorn with Eventlet or Gevent arbiter, see -usage for more information.

+

Replace eventlet with gevent to use to the gevent based workers.

Note

-

If eventlet or gevent fails to install for you, its most likely -due to an out of date libev library. You'll need to download and install -a newer version for either of those to modules to work properly.

+

If you encounter errors when compiling the extensions for Eventlet or +Gevent you most likely need to install a newer version of libev.

Installing on Ubuntu/Debian systems

-

If you use Ubuntu karmic, you can update your -system with packages from our PPA by adding ppa:bchesneau/gunicorn -to your system's Software Sources.

+

If you use Ubuntu karmic, you can update your system with packages from +our PPA by adding ppa:bchesneau/gunicorn to your system's Software +Sources.

Or this PPA can be added to your system manually by copying the lines below and adding them to your system's software sources:

diff --git a/doc/htdocs/news.html b/doc/htdocs/news.html
index 4c8e1ecdd..ffad827b0 100644
--- a/doc/htdocs/news.html
+++ b/doc/htdocs/news.html
@@ -61,14 +61,15 @@ 
0.8.1 / 2010-04-29

 

 
0.8.0 / 2010-04-22

 
    
-
  • Refactored Worker management for better async support. Now use the -k option to set the type of request processing to use
    • 
+
  • Refactored Worker management for better async support. Now use the -k option
+to set the type of request processing to use
    • 
 
  • Added support for Tornado
    • 
 

 

 

 
0.7.2 / 2010-04-15

 
    
-
  • Added --spew option to help debugging (install a Trace hook)
    • 
+
  • Added --spew option to help debugging (installs a system trace hook)
    • 
 
  • Some fixes in async arbiters
    • 
 
  • Fix a bug in start_response on error
    • 
 

@@ -82,7 +83,7 @@ 
0.7.1 / 2010-04-01

 

 
0.7.0 / 2010-03-26

 
    
-
  • Added support for sleepy applications using Eventlet or Gevent.
    • 
+
  • Added support for Eventlet and Gevent based workers.
    • 
 
  • Added Websockets support
    • 
 
  • Fix Chunked Encoding
    • 
 
  • Fix SIGWINCH on OpenBSD
    • 
@@ -92,7 +93,7 @@ 
    0.7.0 / 2010-03-26
    
 
    
 
    0.6.5 / 2010-03-11
    
 
      
-
    • Fix pidfile
      • 
+
    • Fix pidfile handling
      • 
 
    • Fix Exception Error
      • 
 
    
 
    
@@ -107,7 +108,7 @@ 
    0.6.4 / 2010-03-08
    
 
    0.6.3 / 2010-03-07
    
 
      
 
    • Make HTTP parsing faster.
      • 
-
    • Some fixes (see logs)
      • 
+
    • Various bug fixes
      • 
 
    
 

 

@@ -115,7 +116,8 @@ 
0.6.2 / 2010-03-01

 
    
 
  • Added support for chunked response.
    • 
 
  • Added proc_name option to the config file.
    • 
-
  • Improved the HTTP parser. It now uses buffers instead of strings to store temporary data.
    • 
+
  • Improved the HTTP parser. It now uses buffers instead of strings to store
+temporary data.
    • 
 
  • Improved performance when sending responses.
    • 
 
  • Workers are now murdered by age (the oldest is killed first).
    • 
 

@@ -123,7 +125,7 @@ 
0.6.2 / 2010-03-01

 

 
0.6.1 / 2010-02-24

 
    
-
  • Added gunicorn config file support for django admin command
    • 
+
  • Added gunicorn config file support for Django admin command
    • 
 
  • Fix gunicorn config file. -c was broken.
    • 
 
  • Removed TTIN/TTOU from workers which blocked other signals.
    • 
 

@@ -131,15 +133,16 @@ 
0.6.1 / 2010-02-24

 

 
0.6 / 2010-02-22

 
    
-
  • Added setproctitle
    • 
-
  • Change privilege switch behaviour. We now work like NGINX, master keeps the permissions, new uid/gid permissions are only set for workers.
    • 
+
  • Added setproctitle support
    • 
+
  • Change privilege switch behavior. We now work like NGINX, master keeps the
+permissions, new uid/gid permissions are only set for workers.
    • 
 

 

 

 
0.5.1 / 2010-02-22

 
    
 
  • Fix umask
    • 
-
  • Added debian packaging
    • 
+
  • Added Debian packaging
    • 
 

 

 

@@ -153,7 +156,7 @@ 
0.5 / 2010-02-20

 
  • Added umask option
    • 
 
  • Added SCRIPT_NAME support
    • 
 
  • Better support of some exotic settings for Django projects
    • 
-
  • Better support of Paste-compatible applicatins
    • 
+
  • Better support of Paste-compatible applications
    • 
 
  • Some refactoring to make the code easier to hack
    • 
 
  • Allow multiple keys in request and response headers
    • 
 
diff --git a/doc/htdocs/tuning.html b/doc/htdocs/tuning.html
index 52bd95a35..83dbf3e5f 100644
--- a/doc/htdocs/tuning.html
+++ b/doc/htdocs/tuning.html
@@ -51,31 +51,48 @@ 
    gunicorn
    
 
    Tuning
    
 
    
 
    Unicorn Configuration
    
-
    DO NOT scale the number of workers to the number of clients you expect to have. Gunicorn should only need 4-12 worker processes to handle hundreds or thousands of simultaneous clients. Remember, Gunicorn is NOT designed for serving slow clients, that's the job of Nginx.
    
+
    DO NOT scale the number of workers to the number of clients you expect to have.
+Gunicorn should only need 4-12 worker processes to handle hundreds or thousands
+of simultaneous clients. Remember, Gunicorn is NOT designed for serving slow
+clients, that's the job of Nginx.
    
 
    See Configuration for a more thorough description of the available parameters.
    
 
    
 
    
 
    Kernel Parameters
    
-
    When dealing with large numbers of concurrent connections there are a handful of kernel parameters that you might need to adjust. Generally these should only affect sites with a very large concurrent load. These parameters are not specific to Gunicorn, they would apply to any sort of network server you may be running.
    
-
    The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use slightly different flags. Always reference the appropriate man pages if uncertain.
    
+
    When dealing with large numbers of concurrent connections there are a handful of
+kernel parameters that you might need to adjust. Generally these should only
+affect sites with a very large concurrent load. These parameters are not
+specific to Gunicorn, they would apply to any sort of network server you may be
+running.
    
+
    The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use
+slightly different flags. Always reference the appropriate man pages if
+uncertain.
    
 
    
 
    File Descriptor Limits
    
-
    One of the first settings that usually needs to be bumped is the maximum number of open file descriptors for a given process. For the confused out there, remember that Unices treat sockets as files.
    
+
    One of the first settings that usually needs to be bumped is the maximum number
+of open file descriptors for a given process. For the confused out there,
+remember that Unices treat sockets as files.
    
 
     $ sudo ulimit -n 2048
 
    
 
    
 
    
 
    Listen Queue Size
    
-
    Listening sockets have an associated queue of incoming connections that are waiting to be accepted. If you happen to have a stampede of clients that fill up this queue new connections will eventually start getting dropped.
    
+
    Listening sockets have an associated queue of incoming connections that are
+waiting to be accepted. If you happen to have a stampede of clients that fill up
+this queue new connections will eventually start getting dropped.
    
 
     $ sudo sysctl -w kern.ipc.somaxconn="2048"
 
    
 
    
 
    
 
    Ephemeral Port Range
    
-
    After a socket is closed it enters the TIME_WAIT state. This can become an issue after a prolonged burst of client activity. Eventually the ephemeral port range is exhausted which can cause new connections to stall while they wait for a valid port.
    
-
    This setting is generally only required on machines that are being used to test a network server.
    
+
    After a socket is closed it enters the TIME_WAIT state. This can become an issue
+after a prolonged burst of client activity. Eventually the ephemeral port range
+is exhausted which can cause new connections to stall while they wait for a
+valid port.
    
+
    This setting is generally only required on machines that are being used to test
+a network server.
    
 
     $ sudo sysctl -w net.inet.ip.portrange.first="8048"
 
    
diff --git a/doc/htdocs/usage.html b/doc/htdocs/usage.html
index 3541fd083..acaf82b1e 100644
--- a/doc/htdocs/usage.html
+++ b/doc/htdocs/usage.html
@@ -47,111 +47,143 @@ 
    gunicorn
    
   
 
    
 
-  
    
-
    Command Line Usage
    
+  
    
+
    Usage
    
+
    After installing Gunicorn you will have access to three command line scripts
+that can be used for serving the various supported web frameworks: gunicorn,
+gunicorn_django, and gunicorn_paster.
    
+
    
+
    Commonly Used Arguments
    
+
    
 
      
-
    • WSGI applications
      • 
-
    • Django projects
      • 
-
    • Paste-compatible projects
      • 
+
    • -c CONFIG, --config=CONFIG - Specify the path to a config file
      • 
+
    • -b BIND, --bind=BIND - Specify a server socket to bind. Server sockets
+can be any of $(HOST), $(HOST):$(PORT), or unix:$(PATH).
+An IP is a valid $(HOST).
      • 
+
    • -w WORKERS, --workers=WORKERS - The number of worker processes. This
+number should generally be between 2-4 workers per core in the server.
+Check the FAQ for ideas on tuning this parameter.
      • 
+
    • -k WORKERCLASS, --worker-class=WORKERCLASS - The type of worker process
+to run. You'll definitely want to read the production page for the
+implications of this parameter. You can set this to egg:gunicorn#$(NAME)
+where $(NAME) is one of sync, eventlet, gevent, or
+tornado. sync is the default.
      • 
+
    • -n APP_NAME, --name=APP_NAME - If setproctitle is installed you can
+adjust the name of Gunicorn process as they appear in the process system
+table (which affects tools like ps and top).
      • 
 
    
-
    
-
    WSGI applications
    
-
    To launch the example application packaged with Gunicorn:
    
+
    
+
    There are various other parameters that affect user privileges, logging, etc.
+You can see the complete list at the bottom of this page or as expected with:
    
 
    -$ cd /path/to/gunicorn/examples/
-$ gunicorn -w 2 test:app
+$ gunicorn -h
 
    
-
    The module test:app specifies the complete module name and WSGI callable.
-You can replace it with anything that is available on your PYTHONPATH like
-such:
    
+
    
+
    
+
    gunicorn
    
+
    The first and most basic script is used to server 'bare' WSGI applications
+that don't require a translation layer. Basic usage:
    
 
    -$ cd ~/
-$ gunicorn -w 12 awesomeproject.wsgi.main:main_app
+$ gunicorn [OPTIONS] APP_MODULE
 
    
-
    To launch the websocket example application using Eventlet:
    
+
    Where APP_MODULE is of the pattern $(MODULE_NAME):$(VARIABLE_NAME). The
+module name can be a full dotted path. The variable name refers to a WSGI
+callable that should be found in the specified module.
    
+
    Example with test app:
    
 
    -$ cd /path/to/gunicorn/examples/
-$ gunicorn -w 12 -k "egg:gunicorn#eventlet" websocket:app
+$ cd examples
+$ gunicorn --workers=2 test:app
 
    
-
    You should then be able to visit http://localhost:8000 to see output.
    
-
    
-
    Full command line usage
    
+
    
+
    
+
    gunicorn_django
    
+
    You might not have guessed it, but this script is used to server Django
+applications. Basic usage:
    
 
    -$ gunicorn --help
-Usage: gunicorn [OPTIONS] [APP_MODULE]
-
-Options:
-  -c CONFIG, --config=CONFIG
-                        Config file. [none]
-  -b BIND, --bind=BIND  Adress to listen on. Ex. 127.0.0.1:8000 or
-                        unix:/tmp/gunicorn.sock
-  -k WORKERCLASS, --worker-class=WORKERCLASS
-                        The type of request processing to use
-                        [egg:gunicorn#sync]
-  -w WORKERS, --workers=WORKERS
-                        Number of workers to spawn. [1]
-  -p PIDFILE, --pid=PIDFILE
-                        set the background PID FILE
-  -D, --daemon          Run daemonized in the background.
-  -m UMASK, --umask=UMASK
-                        Define umask of daemon process
-  -u USER, --user=USER  Change worker user
-  -g GROUP, --group=GROUP
-                        Change worker group
-  -n APP_NAME, --name=APP_NAME
-                        Application name
-  --log-level=LOGLEVEL  Log level below which to silence messages. [info]
-  --log-file=LOGFILE    Log to a file. - equals stdout. [-]
-  -d, --debug           Debug mode. only 1 worker.
-  --spew                Install a trace hook
-  --version             show program's version number and exit
-  -h, --help            show this help message and exit
+$ gunicorn_django [OPTIONS] [SETTINGS_PATH]
 
    
-
    
-
    
-
    
-
    Django Projects
    
-
    Django projects can be handled easily by Gunicorn using the
-gunicorn_django command:
    
+
    By default SETTINGS_PATH will look for settings.py in the current
+directory.
    
+
    Example with your Django project:
    
 
    -$ cd $yourdjangoproject
+$ cd path/to/yourdjangoproject
 $ gunicorn_django --workers=2
 
    
-
    But you can also use the run_gunicorn admin command like the other
-management.py commands.
    
-
    Add "gunicorn" to INSTALLED_APPS in your settings file:
    
+
    Alternatively, you can install some Gunicorn magic directly into your Django
+project and use the provided command for running the server.
    
+
    First you'll need to add gunicorn to your INSTALLED_APPS in the settings
+file:
    
 
     INSTALLED_APPS = (
     ...
     "gunicorn",
 )
 
    
-
    Then run:
    
+
    Then you can run:
    
 
     python manage.py run_gunicorn
 
    
 
    
-
    
-
    Paste-compatible projects
    
-
    For Paste compatible projects (Pylons, TurboGears 2, ...) use the
-gunicorn_paste command:
    
+
    
+
    gunicorn_paster
    
+
    Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
+apologize for the lack of script name creativity. And some usage:
    
 
    -$ cd $yourpasteproject
+$ gunicorn_paster [OPTIONS] paste_config.ini
+
    
+
    Simple example:
    
+
    +$ cd yourpasteproject
 $ gunicorn_paste --workers=2 development.ini
 
    
-
    To use the paster command add a sever section for Gunicorn:
    
+
    If you're wanting to keep on keeping on with the usual paster serve command,
+you can specify the Gunicorn server settings in your configuration file:
    
 
     [server:main]
 use = egg:gunicorn#main
 host = 127.0.0.1
 port = 5000
 
    
-
    And then all you need to do is:
    
+
    And then as per usual:
    
 
    -$ cd $yourpasteproject
+$ cd yourpasteproject
 $ paster serve development.ini workers=2
 
    
 
    
+
    
+
    Full Command Line Usage
    
+
    +$ gunicorn -h
+Usage: gunicorn [OPTIONS] APP_MODULE
+
+Options:
+  -c CONFIG, --config=CONFIG
+                        Config file. [none]
+  -b BIND, --bind=BIND  Adress to listen on. Ex. 127.0.0.1:8000 or
+                        unix:/tmp/gunicorn.sock
+  -w WORKERS, --workers=WORKERS
+                        Number of workers to spawn. [1]
+  -k WORKER_CLASS, --worker-class=WORKER_CLASS
+                        The type of request processing to use
+                        [egg:gunicorn#sync]
+  -p PIDFILE, --pid=PIDFILE
+                        set the background PID FILE
+  -D, --daemon          Run daemonized in the background.
+  -m UMASK, --umask=UMASK
+                        Define umask of daemon process
+  -u USER, --user=USER  Change worker user
+  -g GROUP, --group=GROUP
+                        Change worker group
+  -n PROC_NAME, --name=PROC_NAME
+                        Process name
+  --log-level=LOGLEVEL  Log level below which to silence messages. [info]
+  --log-file=LOGFILE    Log to a file. - equals stdout. [-]
+  -d, --debug           Debug mode. only 1 worker.
+  --spew                Install a trace hook
+  --version             show program's version number and exit
+  -h, --help            show this help message and exit
+
    
+
    
 
    
 
   
diff --git a/doc/site/configuration.rst b/doc/site/configuration.rst
index 3f5427cb9..6a466464d 100644
--- a/doc/site/configuration.rst
+++ b/doc/site/configuration.rst
@@ -4,7 +4,9 @@ title: The Configuration File
 The Configuration File
 ======================
 
-Gunicorn 0.5 introduced the ability to use a Python configuration file. Gunicorn will look for ``gunicorn.conf.py`` in the current working directory or what ever path is specified on the command line with the ``-c`` option.
+Gunicorn 0.5 introduced the ability to use a Python configuration file. Gunicorn
+will look for ``gunicorn.conf.py`` in the current working directory or what ever
+path is specified on the command line with the ``-c`` option.
 
 Example gunicorn.conf.py
 ------------------------
diff --git a/doc/site/deployment.rst b/doc/site/deployment.rst
index 526e86bf2..67837d788 100644
--- a/doc/site/deployment.rst
+++ b/doc/site/deployment.rst
@@ -4,44 +4,37 @@ title: Deployment
 Production Setup
 ================
 
-There are two general classes of configuration for Gunicorn. For the time
-being these will are referred to as "fast clients" and "sleepy applications".
+Synchronous vs Asynchronous workers
+-----------------------------------
 
-Fast Clients
-------------
+The default configuration of Gunicorn assumes that your application code is
+mostly CPU bound. The default worker class is a simple single threaded loop that
+just processes requests as they are received. In general, most applications will
+do just fine with this sort of configuration.
 
-Generally speaking when we say "fast clients" what we really mean is that the
-time taken to process a client from the time a socket is accepted until
-the time the socket is closed is well defined to be short. This means that
-clients are buffered by an upstream proxy (otherwise clients can send or
-receive data slowly) and that your application code does not have major
-blocking sections (a web request to the internet might occasionally take a
-non trivial amount of time).
+This CPU bound assumption is why the default configuration needs to use a
+buffering HTTP proxy like Nginx_ to protect the Gunicorn server. If we allowed
+direct connections a client could send a request slowly thus starving the server
+of free worker processes (because they're all stuck waiting for data).
 
-Traditional webapps are generally fine for fast client configurations.
-Deployments should generally default to this type of configuration unless it is
-known that the application code wants to do long-polling, comet, web sockets or
-has other potentially long operations (on the order of seconds).
+Example use-cases for asynchronous workers:
 
-Sleepy Applications
--------------------
+  * Applications making long blocking calls (Ie, to external web services)
+  * Serving requests directly to the internet
+  * Streaming requests and responses
+  * Long polling
+  * Web sockets
+  * Comet
 
-Any application that requires an undefined amount of time for client processing
-is considered a sleepy application. If you are wanting a platform that is
-capable of handling comet connections, long polling, or potentially long
-blocking operations (requests to external web services, ie Facebook Connect)
-then you'll want to use an async arbiter.
-
-Nginx Config for fast clients handling
---------------------------------------
+Basic Nginx Configuration
+-------------------------
 
 Although there are many HTTP proxies available, we strongly advise that you
 use Nginx_. If you choose another proxy server you need to make sure that it
-buffers slow clients when you use default Gunicorn arbiter. Without this
+buffers slow clients when you use default Gunicorn workers. Without this
 buffering Gunicorn will be easily susceptible to Denial-Of-Service attacks.
 You can use slowloris_ to check if your proxy is behaving properly.
 
-
 An `example configuration`_ file for fast clients with Nginx_::
 
     worker_processes 1;
@@ -95,8 +88,13 @@ An `example configuration`_ file for fast clients with Nginx_::
         }
     }
 
-To handle sleepy applications, just add the line `proxy_buffering off;` under
-the proxy_redirect directive::
+If you want to be able to handle streaming request/responses or other fancy
+features like Comet, Long polling, or Web sockets, you need to turn off the
+proxy buffering. **When you do this** you must run with one of the async worker
+classes.
+
+To turn off buffering, you only need to add ``proxy_buffering off;`` to your
+``location`` block::
 
   ...
   location / {
@@ -110,7 +108,7 @@ the proxy_redirect directive::
           break;
       }
   }
-  ....
+  ...
 
 Working with Virtualenv
 -----------------------
diff --git a/doc/site/faq.rst b/doc/site/faq.rst
index 0f8849198..2e82754d3 100644
--- a/doc/site/faq.rst
+++ b/doc/site/faq.rst
@@ -4,21 +4,18 @@ title: FAQ
 FAQ
 ===
 
-What is a fast client?
-  Generally speaking a fast client is something that is being served over the
-  local network or from the same machine. This generally would refer to requests
-  forwarded from an upstream proxy. Also see the above FAQ for what a fast
-  client is not.
-
-What is a slow client?
-  A slow client is defined as a request that can take an arbitrary amount of
-  time to send a request or read a response. Sometimes due to network
-  performance or because it is a malicious client attempting to cause problems.
-  Check out the slowloris_ script to generate slow client traffic.
-
-What are sleepy applications?
-  Applications that expect long request/response times and/or slow clients.
-  Gunicorn use `Eventlet`_ or `Gevent`_ to manage concurrency.
+How do I know which type of worker to use?
+  Test. Read the "Synchronous vs Asynchronous workers" section on the 
+  deployment_ page. Test some more.
+
+What types of workers are there?
+  These can all be used with the ``-k`` option and specifying them
+  as ``egg:gunicorn#$(NAME)`` where ``$(NAME)`` is chosen from this list.
+  
+  * ``sync`` - The default synchronous worker
+  * ``eventlet`` - Asynchronous workers based on Greenlets
+  * ``gevent`` - Asynchronous workers based on Greenlets
+  * ``tornado`` - Asynchronous workers based on FriendFeed's Tornado server.
 
 How might I test a proxy configuration?
   Check out slowloris_ for a script that will generate significant slow
@@ -30,7 +27,6 @@ How do I reload my application in Gunicorn?
 
     $ kill -HUP masterpid
 
-
 How do I increase or decrease the number of running workers dynamically?
     To increase the worker count by one::
 
@@ -40,16 +36,20 @@ How do I increase or decrease the number of running workers dynamically?
 
         $ kill -TTOU $masterpid
 
-  
+How can I figure out the best number of worker processes?
+  Start gunicorn with an approximate number of worker processes. Then use the
+  TTIN and/or TTOU signals to adjust the number of workers under load.
+
 How do I set SCRIPT_NAME?
     By default ``SCRIPT_NAME`` is an empy string. The value could be set by
     setting ``SCRIPT_NAME`` in the environment or as an HTTP header.
 
-How to name processes?
-    You need to install the Python package setproctitle_. Then you can name
-    your process with `-n` or just let the default. If you use a configuration
-    file you can set the process name with the proc_name option.
+How can I name processes?
+    You need to install the Python package setproctitle_. Then you can specify
+    a base process name on the command line (``-n``) or in the configuration
+    file.
 
+.. _deployment: http://gunicorn.org/deployment.html
 .. _slowloris: http://ha.ckers.org/slowloris/
 .. _setproctitle: http://pypi.python.org/pypi/setproctitle
 .. _Eventlet: http://eventlet.net
diff --git a/doc/site/index.rst b/doc/site/index.rst
index be635deaf..9127f735e 100644
--- a/doc/site/index.rst
+++ b/doc/site/index.rst
@@ -3,18 +3,19 @@ template: index.html
 Green Unicorn
 =============
 
-Green Unicorn (gunicorn) is an HTTP/WSGI Server for UNIX designed to serve
-`fast clients`_ or `sleepy applications`_.
+Gunicorn 'Green Unicorn' is a WSGI_ HTTP Server for UNIX. It's a pre-fork
+worker model ported from Ruby's Unicorn_ project. The Gunicorn server is
+broadly compatible with various web frameworks, simply implemented, light
+on server resource usage, and fairly speedy.
 
-This is a port of Unicorn_ in Python. Meet us on the `#gunicorn IRC channel`_
-on Freenode_.
+Feel free to join us in `#gunicorn`_ on freenode_.
 
 Gunicorn is released under the MIT License. See the LICENSE_ for more details.
 
 Features
 --------
 
-- Designed for Unix, WSGI_, fast clients and sleepy applications.
+- Designed for Unix.
 - Compatible with Python 2.x (>= 2.5)
 - Easy integration with Django_ and Paster_ compatible applications
   (`Pylons`_, `TurboGears 2`_, ...)
@@ -35,15 +36,13 @@ Applications
   (`Pylons`_, `TurboGears 2`_, ...)
 * Websockets (see the example_ or the screencast_)
 * Reverse proxy implementation (with `Restkit WSGI proxy`_)
-* Comet
 * Long Polling
+* Comet
 
 .. _WSGI:  http://www.python.org/dev/peps/pep-0333/
-.. _`fast clients`: faq.html
-.. _`sleepy applications`: faq.html
 .. _Unicorn: http://unicorn.bogomips.org/
-.. _`#gunicorn IRC channel`: http://webchat.freenode.net/?channels=gunicorn
-.. _Freenode: http://freenode.net
+.. _`#gunicorn`: http://webchat.freenode.net/?channels=gunicorn
+.. _freenode: http://freenode.net
 .. _LICENSE: http://github.com/benoitc/gunicorn/blob/master/LICENSE
 .. _Gunicorn: http://gunicorn.org
 .. _Django: http://djangoproject.com
diff --git a/doc/site/installation.rst b/doc/site/installation.rst
index cc1f74c8d..548375a83 100644
--- a/doc/site/installation.rst
+++ b/doc/site/installation.rst
@@ -7,7 +7,7 @@ Installation
 Requirements
 ------------
 
-- **Python 2.5 or newer** (Python 3.x will be supported soon)
+- **Python 2.x >= 2.5** (Python 3.x will be supported soon)
 - setuptools >= 0.6c6
 - nosetests (for the test suite only)
 
@@ -27,7 +27,7 @@ To install or upgrade to the latest released version of Gunicorn::
 Installing from source
 ----------------------
 
-You can install Gunicorn from source as simply as you would install any other
+You can install Gunicorn from source just as you would install any other
 Python package. Gunicorn uses setuptools which will automatically fetch all
 dependencies (including setuptools itself).
 
@@ -39,11 +39,8 @@ fetch them with git_::
 
     $ git clone git://github.com/benoitc/gunicorn.git
 
-.. _`GitHub Downloads`: http://github.com/benoitc/gunicorn/downloads
-.. _git: http://git-scm.com/
-
 Installation
-++++++++++++++++
+++++++++++++
 
 ::
 
@@ -56,33 +53,30 @@ well as make changes to the source::
 
   $ python setup.py develop
   
-Installation requirements for sleepy application handling
----------------------------------------------------------
+Enabling async workers
+----------------------
 
-If you want to handle `sleepy application `_ you will need to install
-`Eventlet`_ or `Gevent`_.
+You may also want to install Eventlet_ or Gevent_ if you expect that your
+application code may need to pause for extended periods of time during
+request processing. Check out the FAQ_ for more information on when you'll
+want to consider one of the alternate worker types.
 
 To install eventlet::
 
-  $ easy_install -U eventlet
-  
-Replace ``eventlet`` with ``gevent`` if you want to use the ``gevent``
-arbiter.
+    $ easy_install -U eventlet
 
-You can now launch gunicorn with Eventlet or Gevent arbiter, see
-`usage `_ for more information.
+Replace ``eventlet`` with ``gevent`` to use to the ``gevent`` based workers.
 
 .. note::
-    If ``eventlet`` or ``gevent`` fails to install for you, its most likely
-    due to an out of date libev_ library. You'll need to download and install
-    a newer version for either of those to modules to work properly.
+    If you encounter errors when compiling the extensions for Eventlet_ or
+    Gevent_ you most likely need to install a newer version of libev_.
   
 Installing on Ubuntu/Debian systems
 -----------------------------------
 
-If you use `Ubuntu `_ karmic, you can update your
-system with packages from our PPA_ by adding ``ppa:bchesneau/gunicorn``
-to your system's Software Sources.
+If you use Ubuntu_ karmic, you can update your system with packages from
+our PPA_ by adding ``ppa:bchesneau/gunicorn`` to your system's Software
+Sources.
 
 Or this PPA can be added to your system manually by copying the lines below
 and adding them to your system's software sources::
@@ -98,7 +92,11 @@ Fingerprint::
 
   49AEEDFF5CDCD82CEA8AB4DABC981A8115E5EB06
 
+.. _`GitHub Downloads`: http://github.com/benoitc/gunicorn/downloads
+.. _FAQ: faq.html
+.. _git: http://git-scm.com/
 .. _Eventlet: http://eventlet.net
 .. _Gevent: http://gevent.org
 .. _libev: http://software.schmorp.de/pkg/libev.html
+.. _Ubuntu: http://www.ubuntu.com/
 .. _PPA: https://launchpad.net/~bchesneau/+archive/gunicorn
\ No newline at end of file
diff --git a/doc/site/news.rst b/doc/site/news.rst
index 5278be321..6555c4def 100644
--- a/doc/site/news.rst
+++ b/doc/site/news.rst
@@ -15,14 +15,15 @@ News
 0.8.0 / 2010-04-22
 ------------------
 
-- Refactored Worker management for better async support. Now use the -k option to set the type of request processing to use
-- Added support for `Tornado `_ 
+- Refactored Worker management for better async support. Now use the -k option
+  to set the type of request processing to use
+- Added support for Tornado_
 
 
 0.7.2 / 2010-04-15
 ------------------
 
-- Added --spew option to help debugging (install a Trace hook)
+- Added --spew option to help debugging (installs a system trace hook)
 - Some fixes in async arbiters
 - Fix a bug in start_response on error
 
@@ -34,16 +35,16 @@ News
 0.7.0 / 2010-03-26
 ------------------
 
-- Added support for `sleepy applications `_ using Eventlet_ or Gevent_.
+- Added support for Eventlet_ and Gevent_ based workers.
 - Added Websockets_ support
 - Fix Chunked Encoding
 - Fix SIGWINCH on OpenBSD_
-- Fix `PEP 333 `_ compliance for the write callable.
+- Fix `PEP 333`_ compliance for the write callable.
 
 0.6.5 / 2010-03-11
 ------------------
 
-- Fix pidfile
+- Fix pidfile handling
 - Fix Exception Error
 
 0.6.4 / 2010-03-08
@@ -56,14 +57,15 @@ News
 ------------------
 
 * Make HTTP parsing faster.
-* Some fixes (see `logs `_)
+* Various bug fixes
 
 0.6.2 / 2010-03-01
 ------------------
 
 * Added support for chunked response.
 * Added proc_name option to the config file.
-* Improved the HTTP parser. It now uses buffers instead of strings to store temporary data.
+* Improved the HTTP parser. It now uses buffers instead of strings to store
+  temporary data.
 * Improved performance when sending responses.
 * Workers are now murdered by age (the oldest is killed first).
 
@@ -71,21 +73,22 @@ News
 0.6.1 / 2010-02-24
 ------------------
 
-* Added gunicorn config file support for django admin command
+* Added gunicorn config file support for Django admin command
 * Fix gunicorn config file. -c was broken.
 * Removed TTIN/TTOU from workers which blocked other signals.
 
 0.6 / 2010-02-22
 ------------------
 
-* Added setproctitle
-* Change privilege switch behaviour. We now work like NGINX, master keeps the permissions, new uid/gid permissions are only set for workers.
+* Added setproctitle support
+* Change privilege switch behavior. We now work like NGINX, master keeps the
+  permissions, new uid/gid permissions are only set for workers.
 
 0.5.1 / 2010-02-22
 ------------------
 
 * Fix umask
-* Added debian packaging
+* Added Debian packaging
 
 0.5 / 2010-02-20 
 ----------------
@@ -98,10 +101,12 @@ News
 * Added umask option
 * Added SCRIPT_NAME support
 * Better support of some exotic settings for Django projects
-* Better support of Paste-compatible applicatins
+* Better support of Paste-compatible applications
 * Some refactoring to make the code easier to hack
 * Allow multiple keys in request and response headers
 
+.. _Tornado: http://www.tornadoweb.org/
+.. _`PEP 333`: http://www.python.org/dev/peps/pep-0333/
 .. _Eventlet: http://eventlet.net
 .. _Gevent: http://gevent.org
 .. _OpenBSD: http://openbsd.org
diff --git a/doc/site/tuning.rst b/doc/site/tuning.rst
index 1587628d4..7c9770304 100644
--- a/doc/site/tuning.rst
+++ b/doc/site/tuning.rst
@@ -7,7 +7,10 @@ Tuning
 Unicorn Configuration
 ---------------------
 
-DO NOT scale the number of workers to the number of clients you expect to have. Gunicorn should only need 4-12 worker processes to handle hundreds or thousands of simultaneous clients. Remember, Gunicorn is **NOT** designed for serving slow clients, that's the job of Nginx_.
+DO NOT scale the number of workers to the number of clients you expect to have.
+Gunicorn should only need 4-12 worker processes to handle hundreds or thousands
+of simultaneous clients. Remember, Gunicorn is **NOT** designed for serving slow
+clients, that's the job of Nginx_.
 
 See Configuration_ for a more thorough description of the available parameters.
 
@@ -17,14 +20,22 @@ See Configuration_ for a more thorough description of the available parameters.
 Kernel Parameters
 -----------------
 
-When dealing with large numbers of concurrent connections there are a handful of kernel parameters that you might need to adjust. Generally these should only affect sites with a very large concurrent load. These parameters are not specific to Gunicorn, they would apply to any sort of network server you may be running.
+When dealing with large numbers of concurrent connections there are a handful of
+kernel parameters that you might need to adjust. Generally these should only
+affect sites with a very large concurrent load. These parameters are not
+specific to Gunicorn, they would apply to any sort of network server you may be
+running.
 
-The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use slightly different flags. Always reference the appropriate man pages if uncertain.
+The commands listed are tested under Mac OS X 10.6. Your flavor of Unix may use
+slightly different flags. Always reference the appropriate man pages if
+uncertain.
 
 File Descriptor Limits
 ++++++++++++++++++++++
 
-One of the first settings that usually needs to be bumped is the maximum number of open file descriptors for a given process. For the confused out there, remember that Unices treat sockets as files.
+One of the first settings that usually needs to be bumped is the maximum number
+of open file descriptors for a given process. For the confused out there,
+remember that Unices treat sockets as files.
 
 ::
     
@@ -33,7 +44,9 @@ One of the first settings that usually needs to be bumped is the maximum number
 Listen Queue Size
 +++++++++++++++++
 
-Listening sockets have an associated queue of incoming connections that are waiting to be accepted. If you happen to have a stampede of clients that fill up this queue new connections will eventually start getting dropped.
+Listening sockets have an associated queue of incoming connections that are
+waiting to be accepted. If you happen to have a stampede of clients that fill up
+this queue new connections will eventually start getting dropped.
 
 ::
 
@@ -42,9 +55,13 @@ Listening sockets have an associated queue of incoming connections that are wait
 Ephemeral Port Range
 ++++++++++++++++++++
 
-After a socket is closed it enters the TIME_WAIT state. This can become an issue after a prolonged burst of client activity. Eventually the ephemeral port range is exhausted which can cause new connections to stall while they wait for a valid port.
+After a socket is closed it enters the TIME_WAIT state. This can become an issue
+after a prolonged burst of client activity. Eventually the ephemeral port range
+is exhausted which can cause new connections to stall while they wait for a
+valid port.
 
-This setting is generally only required on machines that are being used to test a network server.
+This setting is generally only required on machines that are being used to test
+a network server.
 
 ::
 
diff --git a/doc/site/usage.rst b/doc/site/usage.rst
index 2594a4fbf..066815a5f 100644
--- a/doc/site/usage.rst
+++ b/doc/site/usage.rst
@@ -1,120 +1,148 @@
 template: doc.html
 title: Command Line Usage
 
-Command Line Usage
-==================
+Usage
+=====
 
-- `WSGI applications`_
-- `Django projects`_
-- `Paste-compatible projects`_
+After installing Gunicorn you will have access to three command line scripts
+that can be used for serving the various supported web frameworks: ``gunicorn``,
+``gunicorn_django``, and ``gunicorn_paster``.
 
-WSGI applications
------------------
+Commonly Used Arguments
++++++++++++++++++++++++
+
+  * ``-c CONFIG, --config=CONFIG`` - Specify the path to a `config file`_
+  * ``-b BIND, --bind=BIND`` - Specify a server socket to bind. Server sockets
+    can be any of ``$(HOST)``, ``$(HOST):$(PORT)``, or ``unix:$(PATH)``.
+    An IP is a valid ``$(HOST)``.
+  * ``-w WORKERS, --workers=WORKERS`` - The number of worker processes. This
+    number should generally be between 2-4 workers per core in the server.
+    Check the FAQ_ for ideas on tuning this parameter.
+  * ``-k WORKERCLASS, --worker-class=WORKERCLASS`` - The type of worker process
+    to run. You'll definitely want to read the `production page`_ for the
+    implications of this parameter. You can set this to ``egg:gunicorn#$(NAME)``
+    where ``$(NAME)`` is one of ``sync``, ``eventlet``, ``gevent``, or
+    ``tornado``. ``sync`` is the default.
+  * ``-n APP_NAME, --name=APP_NAME`` - If setproctitle_ is installed you can
+    adjust the name of Gunicorn process as they appear in the process system
+    table (which affects tools like ``ps`` and ``top``).
+
+There are various other parameters that affect user privileges, logging, etc.
+You can see the complete list at the bottom of this page or as expected with::
+
+    $ gunicorn -h
+
+gunicorn
+++++++++
 
-To launch the `example application`_ packaged with Gunicorn::
+The first and most basic script is used to server 'bare' WSGI applications
+that don't require a translation layer. Basic usage::
 
-    $ cd /path/to/gunicorn/examples/
-    $ gunicorn -w 2 test:app
+    $ gunicorn [OPTIONS] APP_MODULE
 
-The module ``test:app`` specifies the complete module name and WSGI callable.
-You can replace it with anything that is available on your ``PYTHONPATH`` like
-such::
+Where ``APP_MODULE`` is of the pattern ``$(MODULE_NAME):$(VARIABLE_NAME)``. The
+module name can be a full dotted path. The variable name refers to a WSGI
+callable that should be found in the specified module.
 
-    $ cd ~/
-    $ gunicorn -w 12 awesomeproject.wsgi.main:main_app
+Example with test app::
+
+    $ cd examples
+    $ gunicorn --workers=2 test:app
     
-To launch the `websocket example`_ application using `Eventlet`_::
+gunicorn_django
++++++++++++++++
 
-        $ cd /path/to/gunicorn/examples/
-        $ gunicorn -w 12 -k "egg:gunicorn#eventlet" websocket:app
+You might not have guessed it, but this script is used to server Django
+applications. Basic usage::
 
-You should then be able to visit ``http://localhost:8000`` to see output.
+    $ gunicorn_django [OPTIONS] [SETTINGS_PATH]
 
-Full command line usage
-+++++++++++++++++++++++
+By default ``SETTINGS_PATH`` will look for ``settings.py`` in the current
+directory.
 
-::
+Example with your Django project::
 
-  $ gunicorn --help
-  Usage: gunicorn [OPTIONS] [APP_MODULE]
-  
-  Options:
-    -c CONFIG, --config=CONFIG
-                          Config file. [none]
-    -b BIND, --bind=BIND  Adress to listen on. Ex. 127.0.0.1:8000 or
-                          unix:/tmp/gunicorn.sock
-    -k WORKERCLASS, --worker-class=WORKERCLASS
-                          The type of request processing to use
-                          [egg:gunicorn#sync]
-    -w WORKERS, --workers=WORKERS
-                          Number of workers to spawn. [1]
-    -p PIDFILE, --pid=PIDFILE
-                          set the background PID FILE
-    -D, --daemon          Run daemonized in the background.
-    -m UMASK, --umask=UMASK
-                          Define umask of daemon process
-    -u USER, --user=USER  Change worker user
-    -g GROUP, --group=GROUP
-                          Change worker group
-    -n APP_NAME, --name=APP_NAME
-                          Application name
-    --log-level=LOGLEVEL  Log level below which to silence messages. [info]
-    --log-file=LOGFILE    Log to a file. - equals stdout. [-]
-    -d, --debug           Debug mode. only 1 worker.
-    --spew                Install a trace hook
-    --version             show program's version number and exit
-    -h, --help            show this help message and exit
-
-Django Projects
----------------
-
-`Django`_ projects can be handled easily by Gunicorn using the
-``gunicorn_django`` command::
-
-    $ cd $yourdjangoproject
+    $ cd path/to/yourdjangoproject
     $ gunicorn_django --workers=2
 
-But you can also use the ``run_gunicorn`` `admin command`_ like the other
-``management.py`` commands.
+Alternatively, you can install some Gunicorn magic directly into your Django
+project and use the provided command for running the server.
 
-Add ``"gunicorn"`` to INSTALLED_APPS in your settings file::
+First you'll need to add ``gunicorn`` to your ``INSTALLED_APPS`` in the settings
+file::
 
     INSTALLED_APPS = (
         ...
         "gunicorn",
     )
   
-Then run::
+Then you can run::
 
     python manage.py run_gunicorn
-  
 
-Paste-compatible projects
--------------------------
+gunicorn_paster
++++++++++++++++
+
+Yeah, for Paster-compatible frameworks (Pylons, TurboGears 2, ...). We
+apologize for the lack of script name creativity. And some usage::
 
-For `Paste`_ compatible projects (`Pylons`_, `TurboGears 2`_, ...) use the
-``gunicorn_paste`` command::
+    $ gunicorn_paster [OPTIONS] paste_config.ini
 
-    $ cd $yourpasteproject
+Simple example::
+
+    $ cd yourpasteproject
     $ gunicorn_paste --workers=2 development.ini
 
-To use the ``paster`` command add a sever section for Gunicorn::
+If you're wanting to keep on keeping on with the usual paster serve command,
+you can specify the Gunicorn server settings in your configuration file::
 
     [server:main]
     use = egg:gunicorn#main
     host = 127.0.0.1
     port = 5000
 
-And then all you need to do is::
+And then as per usual::
 
-    $ cd $yourpasteproject
+    $ cd yourpasteproject
     $ paster serve development.ini workers=2
- 
-.. _`example application`: http://github.com/benoitc/gunicorn/blob/master/examples/test.py
-.. _`websocket example`: http://github.com/benoitc/gunicorn/blob/master/examples/websocket.py
-.. _Django: http://djangoproject.com
-.. _`admin command`: http://docs.djangoproject.com/en/dev/howto/custom-management-commands/
-.. _Paste: http://pythonpaste.org/script/
-.. _Pylons: http://pylonshq.com/
-.. _Turbogears 2: http://turbogears.org/2.0/
-.. _Eventlet: http://eventlet.net
\ No newline at end of file
+
+Full Command Line Usage
++++++++++++++++++++++++
+
+::
+
+    $ gunicorn -h
+    Usage: gunicorn [OPTIONS] APP_MODULE
+
+    Options:
+      -c CONFIG, --config=CONFIG
+                            Config file. [none]
+      -b BIND, --bind=BIND  Adress to listen on. Ex. 127.0.0.1:8000 or
+                            unix:/tmp/gunicorn.sock
+      -w WORKERS, --workers=WORKERS
+                            Number of workers to spawn. [1]
+      -k WORKER_CLASS, --worker-class=WORKER_CLASS
+                            The type of request processing to use
+                            [egg:gunicorn#sync]
+      -p PIDFILE, --pid=PIDFILE
+                            set the background PID FILE
+      -D, --daemon          Run daemonized in the background.
+      -m UMASK, --umask=UMASK
+                            Define umask of daemon process
+      -u USER, --user=USER  Change worker user
+      -g GROUP, --group=GROUP
+                            Change worker group
+      -n PROC_NAME, --name=PROC_NAME
+                            Process name
+      --log-level=LOGLEVEL  Log level below which to silence messages. [info]
+      --log-file=LOGFILE    Log to a file. - equals stdout. [-]
+      -d, --debug           Debug mode. only 1 worker.
+      --spew                Install a trace hook
+      --version             show program's version number and exit
+      -h, --help            show this help message and exit
+
+
+.. _FAQ: faq.html
+.. _`production page`: deployment.html
+.. _`config file`: configuration.html
+.. _setproctitle: http://pypi.python.org/pypi/setproctitle/