api: Improve documentation for real-time-events API.

templates/zerver/api/get-events-from-queue.md

@@ -1,4 +1,4 @@
-# Get new events from an events queue
+# Get events from a queue
 
 `GET {{ api_url }}/v1/events`
 
@@ -44,15 +44,6 @@ print(client.get_events(
     queue_id="1515010080:4",
     last_event_id=-1
 ))
-
-# Print each message the user receives
-# This is a blocking call that will run forever
-client.call_on_each_message(lambda msg: sys.stdout.write(str(msg) + "\n"))
-
-# Print every event relevant to the user
-# This is a blocking call that will run forever
-# This will never be reached unless you comment out the previous line
-client.call_on_each_event(lambda msg: sys.stdout.write(str(msg) + "\n"))
 ```
 
 `call_on_each_message` and `call_on_each_event` will automatically register
@@ -103,10 +94,6 @@ even if you haven't registered a queue by explicitly requesting the
 [the `{{ api_url}}/v1/register` endpoint](/api/register-queue) to this
 endpoint and a queue would be registered in the absence of a `queue_id`.
 
-You may also pass in the following keyword arguments to `call_on_each_event`:
-
-{generate_api_arguments_table|arguments.json|call_on_each_event}
-
 ## Response
 
 #### Return values

templates/zerver/api/real-time-events.md

@@ -0,0 +1,71 @@
+# Real-time events API
+
+Zulip's real-time events API lets you write software that reacts
+immediately to events happening in Zulip.  This API is what powers the
+real-time updates in the Zulip web and mobile apps.  As a result, the
+events available via this API cover all changes to data displayed in
+the Zulip product, from new messages to stream descriptions to
+emoji reactions to changes in user or organization-level settings.
+
+## Using the events API
+
+The simplest way to use Zulip's real-time events API is by using
+`call_on_each_event` from our Python bindings.  You just need to write
+a Python function (in the examples below, the `lambda`s) and pass it
+into `call_on_each_event`; your function will be called whenever a new
+event matching the specific `event_type` and/or `narrow` arguments
+occurs in Zulip.
+
+`call_on_each_event` takes care of all the potentially tricky details
+of long-polling, error handling, exponential backoff in retries, etc.
+It's cousin, `call_on_each_message`, provides an even simpler
+interface for processing Zulip messages.
+
+More complex applications (like a Zulip terminal client) may need to
+instead use the raw [register](/api/register-queue) and
+[events](/api/get-events-from-queue) endpoints.
+
+## Usage examples
+<div class="code-section" markdown="1">
+<ul class="nav">
+<li data-language="python">Python</li>
+</ul>
+<div class="blocks">
+
+<div data-language="python" markdown="1">
+
+```
+#!/usr/bin/env python
+
+import sys
+import zulip
+
+# Download ~/zuliprc-dev from your dev server
+client = zulip.Client(config_file="~/zuliprc-dev")
+
+# Print every message the current user would receive
+# This is a blocking call that will run forever
+client.call_on_each_message(lambda msg: sys.stdout.write(str(msg) + "\n"))
+
+# Print every event relevant to the user
+# This is a blocking call that will run forever
+client.call_on_each_event(lambda event: sys.stdout.write(str(event) + "\n"))
+```
+
+</div>
+</div>
+</div>
+
+## Arguments
+
+You may also pass in the following keyword arguments to `call_on_each_event`:
+
+{generate_api_arguments_table|arguments.json|call_on_each_event}
+
+## Deeper implementation details
+
+If you're developing a Zulip client or otherwise want deeper details,
+you can consult the
+[developer documentation](https://zulip.readthedocs.io/en/latest/subsystems/events-system.html)
+for how Zulip's event system works.
+

templates/zerver/help/include/rest_endpoints.md

@@ -20,8 +20,9 @@
 * [Create a user](/api/create-user)
 * [Upload a file](/api/upload-file)
 
-#### Events
+#### Real-time events
+* [Real time events API](/api/real-time-events)
 * [Register a queue](/api/register-queue)
-* [Get events from queue](/api/get-events-from-queue)
+* [Get events from a queue](/api/get-events-from-queue)
 * [Delete a queue](/api/delete-queue)