Move Usage into a separate page

- strip .rst from toctree entries

1 files changed, 8 insertions, 269 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 58f4cd2..0416370 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,268 +7,6 @@ in the Python standard library.  It runs on CPython on Unix and Windows under
 Python 2.7+ and Python 3.4+.  It is also known to run on PyPy 1.6.0 on UNIX.
 It supports HTTP/1.0 and HTTP/1.1.
 
-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`.
-
-
-.. _logging:
-
-Logging
--------
-
-``waitress.serve`` calls ``logging.basicConfig()`` to set up logging to the
-console when the server starts up.  Assuming no other logging configuration
-has already been done, this sets the logging default level to
-``logging.WARNING``.  The Waitress logger will inherit the root logger's
-level information (it logs at level ``WARNING`` or above).
-
-Waitress sends its logging output (including application exception
-renderings) to the Python logger object named ``waitress``.  You can
-influence the logger level and output stream using the normal Python
-``logging`` module API.  For example:
-
-.. code-block:: python
-
-   import logging
-   logger = logging.getLogger('waitress')
-   logger.setLevel(logging.INFO)
-
-Within a PasteDeploy configuration file, you can use the normal Python
-``logging`` module ``.ini`` file format to change similar Waitress logging
-options.  For example:
-
-.. code-block:: ini
-
-   [logger_waitress]
-   level = INFO
-
-
-Web Traffic Logging With Paste's TransLogging Middleware
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The WSGI design is modular.  Waitress logs error conditions, debugging
-output, etc., but not web traffic.  For web traffic logging Paste
-provides the `TransLogger
-<https://web.archive.org/web/20160707041338/http://pythonpaste.org/modules/translogger.html>`_
-:term:`middleware`.  TransLogger produces logs in the `Apache Combined
-Log Format <https://httpd.apache.org/docs/current/logs.html#combined>`_.
-But TransLogger does not write to files, the Python logging system
-must be configured to do this.  The Python `FileHandler
-<https://docs.python.org/3/library/logging.handlers.html#filehandler>`_
-logging handler can be used alongside TransLogger to create an
-``access.log`` file similar to Apache's.
-
-Like any standard :term:`middleware` with a Paste entry point,
-TransLogger can be configured to wrap your application using ``.ini``
-file syntax.  First add a
-``[filter:translogger]`` section, then use a ``[pipeline:main]``
-section file to form a WSGI pipeline with both the translogger and
-your application in it.  For instance, if you have this:
-
-.. code-block:: ini 
-
-   [app:wsgiapp]
-   use = egg:mypackage#wsgiapp
-
-   [server:main]
-   use = egg:waitress#main
-   host = 127.0.0.1
-   port = 8080
-
-
-Add this:
-
-.. code-block:: ini 
-
-   [filter:translogger] 
-   use = egg:Paste#translogger 
-   setup_console_handler = False
-
-   [pipeline:main]
-   pipeline = translogger
-              wsgiapp
-
-
-Using PasteDeploy this way to form and serve a pipeline is equivalent to
-wrapping your app in a TransLogger instance via the bottom of the ``main``
-function of your project's ``__init__`` file:
-
-.. code-block:: python 
-
-
-    from mypackage import wsgiapp
-    from waitress import serve
-    from paste.translogger import TransLogger 
-    serve(TransLogger(wsgiapp, setup_console_handler=False))
-
-
-.. note::
-    TransLogger will automatically setup a logging handler to the console when
-    called with no arguments, so it 'just works' in environments that don't
-    configure logging. Since our logging handlers are configured we disable
-    the automation via ``setup_console_handler = False``.
-
-With the filter in place, TransLogger's logger (named the ``wsgi`` logger) will
-propagate its log messages to the parent logger (the root logger), sending
-its output to the console when we request a page:
-
-.. code-block:: text 
-
-    00:50:53,694 INFO [wsgiapp] Returning: Hello World!
-                      (content-type: text/plain) 
-    00:50:53,695 INFO [wsgi] 192.168.1.111 - - [11/Aug/2011:20:09:33 -0700] "GET /hello
-    HTTP/1.1" 404 - "-" 
-    "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en-US; rv:1.8.1.6) Gecko/20070725
-    Firefox/2.0.0.6" 
-
-To direct TransLogger to an ``access.log`` FileHandler, we need the
-following to add a FileHandler (named ``accesslog``) to the list of
-handlers, and ensure that the ``wsgi`` logger is configured and uses
-this handler accordingly:
-
-.. code-block:: ini 
-
-    # Begin logging configuration 
-
-    [loggers]
-    keys = root, wsgiapp, wsgi
-
-    [handlers]
-    keys = console, accesslog
-
-    [logger_wsgi] 
-    level = INFO 
-    handlers = accesslog
-    qualname = wsgi 
-    propagate = 0 
-
-    [handler_accesslog] 
-    class = FileHandler 
-    args = ('%(here)s/access.log','a') 
-    level = INFO 
-    formatter = generic 
-
-As mentioned above, non-root loggers by default propagate their log records
-to the root logger's handlers (currently the console handler). Setting
-``propagate`` to ``0`` (``False``) here disables this; so the ``wsgi`` logger 
-directs its records only to the ``accesslog`` handler.
-
-Finally, there's no need to use the ``generic`` formatter with
-TransLogger as TransLogger itself provides all the information we
-need. We'll use a formatter that passes-through the log messages as
-is. Add a new formatter called ``accesslog`` by including the
-following in your configuration file:
-
-.. code-block:: ini 
-
-    [formatters] 
-    keys = generic, accesslog 
-
-    [formatter_accesslog] 
-    format = %(message)s 
-
-Finally alter the existing configuration to wire this new
-``accesslog`` formatter into the FileHandler:
-
-.. code-block:: ini 
-
-    [handler_accesslog] 
-    class = FileHandler 
-    args = ('%(here)s/access.log','a') 
-    level = INFO 
-    formatter = accesslog 
 
 
 
@@ -439,13 +177,14 @@ Extended Documentation
 .. toctree::
    :maxdepth: 1
 
-   design.rst
-   differences.rst
-   api.rst
-   arguments.rst
-   filewrapper.rst
-   runner.rst
-   glossary.rst
+   usage
+   design
+   differences
+   api
+   arguments
+   filewrapper
+   runner
+   glossary
 
 Change History
 --------------