Move Usage into a separate page

1 files changed, 97 insertions, 0 deletions

diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..ddcd4b8
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,97 @@
+.. _usage:
+
+=====
+Usage
+=====
+
+Here's normal usage of the server:
+
+.. code-block:: python
+
+   from waitress import serve
+   serve(wsgiapp, listen='*:8080')
+
+This will run waitress on port 8080 on all available IP addresses, both IPv4
+and IPv6.
+
+
+.. code-block:: python
+
+   from waitress import serve
+   serve(wsgiapp, host='0.0.0.0', port=8080)
+
+This will run waitress on port 8080 on all available IPv4 addresses.
+
+If you want to serve your application on all IP addresses, on port 8080, you
+can omit the ``host`` and ``port`` arguments and just call ``serve`` with the
+WSGI app as a single argument:
+
+.. code-block:: python
+
+   from waitress import serve
+   serve(wsgiapp)
+
+Press Ctrl-C (or Ctrl-Break on Windows) to exit the server.
+
+The default is to bind to any IPv4 address on port 8080:
+
+.. code-block:: python
+
+   from waitress import serve
+   serve(wsgiapp)
+
+If you want to serve your application through a UNIX domain socket (to serve
+a downstream HTTP server/proxy, e.g., nginx, lighttpd, etc.), call ``serve``
+with the ``unix_socket`` argument:
+
+.. code-block:: python
+
+   from waitress import serve
+   serve(wsgiapp, unix_socket='/path/to/unix.sock')
+
+Needless to say, this configuration won't work on Windows.
+
+Exceptions generated by your application will be shown on the console by
+default.  See :ref:`logging` to change this.
+
+There's an entry point for :term:`PasteDeploy` (``egg:waitress#main``) that
+lets you use Waitress's WSGI gateway from a configuration file, e.g.:
+
+.. code-block:: ini
+
+  [server:main]
+  use = egg:waitress#main
+  listen = 127.0.0.1:8080
+
+Using ``host`` and ``port`` is also supported:
+
+.. code-block:: ini
+
+  [server:main]
+  host = 127.0.0.1
+  port = 8080
+
+The :term:`PasteDeploy` syntax for UNIX domain sockets is analagous:
+
+.. code-block:: ini
+
+  [server:main]
+  use = egg:waitress#main
+  unix_socket = /path/to/unix.sock
+
+You can find more settings to tweak (arguments to ``waitress.serve`` or
+equivalent settings in PasteDeploy) in :ref:`arguments`.
+
+Additionally, there is a command line runner called ``waitress-serve``, which
+can be used in development and in situations where the likes of
+:term:`PasteDeploy` is not necessary:
+
+.. code-block:: bash
+
+   # Listen on both IPv4 and IPv6 on port 8041
+   waitress-serve --listen=*:8041 myapp:wsgifunc
+
+   # Listen on only IPv4 on port 8041
+   waitress-serve --port=8041 myapp:wsgifunc
+
+For more information on this, see :ref:`runner`.