From 8eea5fe2562775e22506a1676c4bcb682b0e4913 Mon Sep 17 00:00:00 2001
From: Tim Schmidt <w4rum@users.noreply.github.com>
Date: Sun, 24 Jan 2021 22:20:32 +0100
Subject: [PATCH] added documentation for server-facing stubs (#186)

---
 README.md            | 30 ++++++++++++++++++++++++++++++
 docs/index.rst       |  2 +-
 docs/quick-start.rst | 32 +++++++++++++++++++++++++++++++-
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c70aca7..b025cbb 100644
--- a/README.md
+++ b/README.md
@@ -192,6 +192,36 @@ EchoStreamResponse(value='hello')
 EchoStreamResponse(value='hello')
 ```
 
+This project also produces server-facing stubs that can be used to implement a Python
+gRPC server.
+To use them, simply subclass the base class in the generated files and override the
+service methods:
+
+```python
+from echo import EchoBase
+from grpclib.server import Server
+from typing import AsyncIterator
+
+
+class EchoService(EchoBase):
+    async def echo(self, value: str, extra_times: int) -> "EchoResponse":
+        return value
+
+    async def echo_stream(
+        self, value: str, extra_times: int
+    ) -> AsyncIterator["EchoStreamResponse"]:
+        for _ in range(extra_times):
+            yield value
+
+
+async def start_server():
+    HOST = "127.0.0.1"
+    PORT = 1337
+    server = Server([EchoService()])
+    await server.start(HOST, PORT)
+    await server.serve_forever()
+```
+
 ### JSON
 
 Both serializing and parsing are supported to/from JSON and Python dictionaries using the following methods:
diff --git a/docs/index.rst b/docs/index.rst
index dfaa8fc..3eabac1 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,7 +12,7 @@ Features:
 - Generated messages are both binary & JSON serializable
 - Messages use relevant python types, e.g. ``Enum``, ``datetime`` and ``timedelta``
   objects
-- ``async``/``await`` support for gRPC Clients
+- ``async``/``await`` support for gRPC Clients and Servers
 - Generates modern, readable, idiomatic python code
 
 Contents:
diff --git a/docs/quick-start.rst b/docs/quick-start.rst
index c731ca2..73598c6 100644
--- a/docs/quick-start.rst
+++ b/docs/quick-start.rst
@@ -100,7 +100,7 @@ Async gRPC Support
 ++++++++++++++++++
 
 The generated code includes `grpclib <https://grpclib.readthedocs.io/en/latest>`_ based
-stub (client) classes for rpc services declared in the input proto files.
+stub (client and server) classes for rpc services declared in the input proto files.
 It is enabled by default.
 
 
@@ -160,6 +160,36 @@ The generated client can be used like so:
     EchoStreamResponse(value='hello')
 
 
+The server-facing stubs can be used to implement a Python
+gRPC server.
+To use them, simply subclass the base class in the generated files and override the
+service methods:
+
+.. code-block:: python
+
+    from echo import EchoBase
+    from grpclib.server import Server
+    from typing import AsyncIterator
+
+
+    class EchoService(EchoBase):
+        async def echo(self, value: str, extra_times: int) -> "EchoResponse":
+            return value
+
+        async def echo_stream(
+            self, value: str, extra_times: int
+        ) -> AsyncIterator["EchoStreamResponse"]:
+            for _ in range(extra_times):
+                yield value
+
+
+    async def start_server():
+        HOST = "127.0.0.1"
+        PORT = 1337
+        server = Server([EchoService()])
+        await server.start(HOST, PORT)
+        await server.serve_forever()
+
 JSON
 ++++
 Message objects include :meth:`betterproto.Message.to_json` and