Serve Doc: Quickstart (#7940)

doc/source/index.rst

@@ -17,12 +17,14 @@ Ray is packaged with the following libraries for accelerating machine learning w
 - `Tune`_: Scalable Hyperparameter Tuning
 - `RLlib`_: Scalable Reinforcement Learning
 - `RaySGD`_: Distributed Training Wrappers
+- `RayServe`_: Scalable and Programmable Serving
 
 
 Star us on `on GitHub`_. You can also get started by visiting our `Tutorials <https://github.com/ray-project/tutorial>`_. For the latest wheels (nightlies), see the `installation page <installation.html>`__.
 
 .. _`on GitHub`: https://github.com/ray-project/ray
 .. _`RaySGD`: raysgd/raysgd.html
+.. _`RayServe`: serve/quickstart.html
 
 .. important:: Join our `community slack <https://forms.gle/9TSdDYUgxYs8SA9e8>`_ to discuss Ray!
 
@@ -281,6 +283,12 @@ Getting Involved
    raysgd/raysgd_tensorflow.rst
    raysgd/raysgd_ref.rst
 
+.. toctree::
+   :maxdepth: -1
+   :caption: RayServe
+
+   serve/quickstart.rst
+
 .. toctree::
    :maxdepth: -1
    :caption: Other Libraries
@@ -289,7 +297,6 @@ Getting Involved
    joblib.rst
    iter.rst
    pandas_on_ray.rst
-   serve.rst
 
 .. toctree::
    :maxdepth: -1

doc/source/serve.rst

@@ -1,23 +0,0 @@
-Ray Serve
-=========
-
-.. _`issue on GitHub`: https://github.com/ray-project/ray/issues
-
-Ray Serve is a serving library that exposes python function/classes to HTTP.
-It has built-in support for flexible traffic policy. This means you can easy
-split incoming traffic to multiple implementations. 
-
-.. warning::
-
-  Ray Serve is under development and its API may be revised in future Ray releases. If you encounter any bugs, please file an `issue on GitHub`_.
-
-With Ray Serve, you can deploy your services at any scale.
-
-Quickstart
-----------
-.. literalinclude:: ../../python/ray/serve/examples/echo_full.py
-
-API
----
-.. automodule:: ray.serve
-    :members:

doc/source/serve/quickstart.rst

@@ -0,0 +1,64 @@
+RayServe: Scalable and Programmable Serving
+============================================
+
+.. image:: logo.svg
+    :align: center
+
+.. note::
+	If you want to try out Serve, join our `community slack <https://forms.gle/9TSdDYUgxYs8SA9e8>`_
+	and discuss in ``#serve`` channel.
+
+There are generally two ways of serving machine learning applications at scale.
+The first is wrapping your application in a traditional web server. This approach
+is easy but hard to scale each component, and easily leading to high memory usage
+as well as concurrency issue. The other approach is to use a cloud-hosted solution
+like SageMaker or TFServing. These solutions have high learning costs and lead to
+vendor lock-in.
+
+Serve is a serving library built on top of ray. It is easy-to-use and flexible.
+
+- Serve is **framework agnostics** and extensible. You can serve your scikit-learn,
+  PyTorch, and TensorFlow models in the same framework.
+- Serve gives you end-to-end control over your API. Your input is just a **Flask
+  request** instead of arrays.
+- Serve scales to many machines. With a single API call, you can run scale your
+  models to hundreds of GPUs.
+- Serve decouples routing and handling so you can update or **A/B test** your models
+  with zero downtime.
+- Serve uses **Python as the configuration language**. Tired of writing repetitive YAMLs
+  or JSON to configure your services? Serve can be configured directly using the
+  Python API.
+- Serve has built-in **batching and SLO awareness**. This means Serve will maximally
+  utilize the hardware and reorder queries to meet your latency objective.
+- With Ray Autoscaler, you can deploy Serve to **any cloud** (or Kubernetes).
+
+
+Quick start
+-----------
+Serve a stateless function:
+
+.. literalinclude:: ../../../python/ray/serve/examples/doc/quickstart_function.py
+
+Serve a stateful class:
+
+.. literalinclude:: ../../../python/ray/serve/examples/doc/quickstart_class.py
+
+
+``@serve.route`` decorator is similar to the Flask ``route`` decorator. You can
+decorate a function or a class. It specifies how request for HTTP is routed to
+your function.
+
+To make your function servable, the function just need to take in a flask
+request as first argument. Your input for web request are just flask request
+object, you don't need to learn new API. To make your class servable, implement
+``__call__`` method taking in the flask request as well.
+
+Learn more
+----------
+- Serve architecture in depth
+- Serve how-to guides
+
+	- Scikit-learn serving with composition
+	- PyTorch serving with batching
+
+- Serve deployment guides

doc/source/tune/.gitignore

@@ -0,0 +1 @@
+generated_guides/

python/ray/serve/BUILD

@@ -18,11 +18,27 @@ py_test(
     deps = [":serve_lib"],
 )
 
-# Make sure the example showing in doc is tested
 py_test(
     name = "echo_full",
     size = "small",
     srcs = glob(["examples/*.py"]),
     tags = ["exclusive"],
     deps = [":serve_lib"]
+)
+
+# Make sure the example showing in doc is tested
+py_test(
+    name = "quickstart_class",
+    size = "small",
+    srcs = glob(["examples/doc/*.py"]),
+    tags = ["exclusive"],
+    deps = [":serve_lib"]
+)
+
+py_test(
+    name = "quickstart_function",
+    size = "small",
+    srcs = glob(["examples/doc/*.py"]),
+    tags = ["exclusive"],
+    deps = [":serve_lib"]
 )

python/ray/serve/examples/doc/quickstart_class.py

@@ -0,0 +1,17 @@
+from ray import serve
+import requests
+
+serve.init()
+
+
+@serve.route("/counter")
+class Counter:
+    def __init__(self):
+        self.count = 0
+
+    def __call__(self, flask_request):
+        return {"current_counter": self.count}
+
+
+requests.get("http://127.0.0.1:8000/counter").json()
+# > {"current_counter": self.count}

python/ray/serve/examples/doc/quickstart_function.py

@@ -0,0 +1,13 @@
+from ray import serve
+import requests
+
+serve.init()
+
+
+@serve.route("/hello")
+def echo(flask_request):
+    return "hello " + flask_request.args.get("name", "serve!")
+
+
+requests.get("http://127.0.0.1:8000/hello").text
+# > "hello serve!"