From 8df8e767fa104154b3a5b83a459192881eb812a1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rafa=C5=82=20Kasa?= <rafalkasa@gmail.com>
Date: Mon, 19 Dec 2016 01:34:36 +0100
Subject: [PATCH] docs(User Guide): Add to the documentation Waitress server
 working with Falcon (#946)

* Waitress server description

* Add Waitress for Windows users

* Add HTTPie for check the example instead only curl

* add how to run complex example from HTTPie

* Add in documentation information about working on Windows Falcon server

* Change POST method call with image

This method is working on windows and unix systems, previous working fine only on unix

* Change call method for upload image file to Falcon server

* docs(User Guide): Add to the documentation Waitress server
---
 docs/user/install.rst    |  6 +++++-
 docs/user/quickstart.rst | 21 +++++++++++++++++++++
 docs/user/tutorial.rst   | 15 +++++++++++----
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/docs/user/install.rst b/docs/user/install.rst
index 851f424..a205721 100644
--- a/docs/user/install.rst
+++ b/docs/user/install.rst
@@ -82,9 +82,13 @@ Falcon speaks WSGI, and so in order to serve a Falcon app, you will
 need a WSGI server. Gunicorn and uWSGI are some of the more popular
 ones out there, but anything that can load a WSGI app will do.
 
+All Windows developers can use Waitress production-quality pure-Python WSGI server with very acceptable performance. 
+Unfortunately Gunicorn is still not working on Windows and uWSGI need to have Cygwin on Windows installed. 
+Waitress can be good alternative for Windows users if they want quick start using Falcon on it.
+
 .. code:: bash
 
-    $ pip install [gunicorn|uwsgi]
+    $ pip install [gunicorn|uwsgi|waitress]
 
 Source Code
 -----------
diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst
index 64930eb..4761590 100644
--- a/docs/user/quickstart.rst
+++ b/docs/user/quickstart.rst
@@ -50,12 +50,27 @@ or Gunicorn. For example:
     $ pip install gunicorn
     $ gunicorn things:app
 
+On Windows where Gunicorn and uWSGI don't work yet you can use Waitress server
+
+.. code:: bash
+
+    $ pip install waitress
+    $ waitress-serve --port=8000 things:app
+    
 Then, in another terminal:
 
 .. code:: bash
 
     $ curl localhost:8000/things
 
+Curl is a bit of a pain to use, so let's install
+`HTTPie <https://github.com/jkbr/httpie>`_ and use it from now on.
+
+.. code:: bash
+
+    $ pip install --upgrade httpie
+    $ http localhost:8000/things
+
 .. _quickstart-more-features:
 
 More Features
@@ -282,3 +297,9 @@ parameters, handling errors, and working with request and response bodies.
     if __name__ == '__main__':
         httpd = simple_server.make_server('127.0.0.1', 8000, app)
         httpd.serve_forever()
+
+To test this example go to the another terminal and run:
+
+.. code:: bash
+
+    $ http localhost:8000/1/things authorization:custom-token
diff --git a/docs/user/tutorial.rst b/docs/user/tutorial.rst
index be7d1ad..4ede89a 100644
--- a/docs/user/tutorial.rst
+++ b/docs/user/tutorial.rst
@@ -88,7 +88,14 @@ let's use something that you would actually deploy in production.
 .. code:: bash
 
     $ pip install gunicorn
-    $ gunicorn app
+    $ gunicorn app:api
+    
+Gunicorn has still limitation that is not working on Windows. If you are Windows user you can use Waitress server instead Gunicorn
+
+.. code:: bash
+
+    $ pip install waitress
+    $ waitress-serve --port=8000 app:api
 
 Now try querying it with curl:
 
@@ -302,7 +309,7 @@ Restart gunicorn, and then try sending a POST request to the resource
 
 .. code:: bash
 
-    $ http POST localhost:8000/images Content-Type:image/jpeg < test.jpg
+    $ http POST localhost:8000/images Content-Type:image/jpeg @/usr/local/images/test.jpg
 
 Now, if you check your storage directory, it should contain a copy of the
 image you just POSTed.
@@ -430,7 +437,7 @@ Now, restart gunicorn and post another picture to the service:
 
 .. code:: bash
 
-    $ http POST localhost:8000/images Content-Type:image/jpeg < test.jpg
+    $ http POST localhost:8000/images Content-Type:image/jpeg @/usr/local/images/test.jpg
 
 Make a note of the path returned in the Location header, and use it to
 try GETing the image:
@@ -536,7 +543,7 @@ POSTed, you can see it in action by passing in something nefarious:
 
 .. code:: bash
 
-    $ http POST localhost:8000/images Content-Type:image/jpx < test.jpx
+    $ http POST localhost:8000/images Content-Type:image/jpx @test.jpx
 
 That should return a ``400 Bad Request`` status and a nicely structured
 error body. When something goes wrong, you usually want to give your users